flowbus gcos 7 cobol - bull on-line support...

FlowBusGCOS 7 COBOL

Programmer's Guide DPS

7000/XTA

NO

VASC

ALE

7000

Distributed Computing

REFERENCE86 A2 63CD 01

DPS7000/XTANOVASCALE 7000

FlowBusGCOS 7 COBOLProgrammer's Guide

Distributed Computing

June 1997

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

REFERENCE86 A2 63CD 01

The following copyright notice protects this book under Copyright laws which prohibit such actions as, but notlimited to, copying, distributing, modifying, and making derivative works.

Copyright Bull SAS 1997

Printed in France

Suggestions and criticisms concerning the form, content, and presentation of thisbook are invited. A form is provided at the end of this book for this purpose.

To order additional copies of this book or other Bull Technical Publications, youare invited to use the Ordering Form also provided at the end of this book.

Trademarks and Acknowledgements

We acknowledge the right of proprietors of trademarks mentioned in this book.

Intel® and Itanium® are registered trademarks of Intel Corporation.

Windows® and Microsoft® software are registered trademarks of Microsoft Corporation.

UNIX® is a registered trademark in the United States of America and other countries licensed exclusively throughthe Open Group.

Linux® is a registered trademark of Linus Torvalds.

The information in this document is subject to change without notice. Bull will not be liable for errors containedherein, or for incidental or consequential damages in connection with the use of this material.

86 A2 63CD Rev01 iii

Preface

The FlowBus GCOS 7 COBOL Programmer's Guide tells you how to prepareapplications that interact over FlowBus. You use the FlowBus Application Programmer'sInterface (API) to do this. This guide contains the following kinds of information:

• Guide-lines for programming with the FlowBus API

• Reference documentation for the routines in the FlowBus API Library

This guide also tells you how to code message classifications.

This preface tells you about this guide and what else you need to know to use theFlowBus API.

Who Should Read this Guide

You should read this guide if you need to do the following tasks:

• Include FlowBus API routines in an existing application

• Set up a wrapper for an existing application

• Create a new application that interacts over FlowBus

• Create message classifications.

The person who does these tasks is called the application programmer. The applicationprogrammer works closely with the application integrator, who includes applications inthe FlowBus configuration.

Assumptions and Prerequisites

You should have read the FlowBus Product Overview. This tells you what FlowBus isand how it works.

You must be familiar with COBOL programming. You must also be familiar with theexisting applications.

FlowBus GCOS 7 COBOL Programmer's Guide

iv 86 A2 63CD Rev01

You should be familiar with TUXEDO programming; at least as much as can be gainedby reading the TUXEDO Product Overview and the Application Development Guide ofthe TUXEDO documentation set.

You should be familiar with the platform on which the applications run.

You must have defined the delivery points and base message types you are going to usefor each application. The application integrator may have done this work for you. Whenyou have set up the interface with FlowBus, you must give the application integratoraccess to it.

Organization of this Guide

This manual is divided into the following chapters:

Chapter 1This chapter outlines the steps that you must take in order to make applications interactover FlowBus. This chapter introduces important concepts and provides an overview ofthe process.

Chapter 2This chapter tells you how you use FlowBus API routines to program high-levelinteractions with FlowBus.

Chapter 3This chapter tells you how you use FlowBus API routines to program low-levelinteractions with FlowBus.

Chapter 4This chapter describes the rules which you must follow to use the FlowBus API routinesin transactions.

Chapter 5This chapter tells you about message classification.

Chapter 6This chapter tells you how to link applications that include FlowBus API routines.

Appendix AThis appendix contains reference documentation for the routines in the FlowBus GCOS 7COBOL API.

Appendix BThis appendix tells you about application instances.

Appendix CThis appendix tells you about the example application supplied with FlowBus.

Preface

86 A2 63CD Rev01 v

Related Documentation

The following manuals form the FlowBus documentation set:

FlowBus Product Overview ......................................................................... 86 A2 51CDFlowBus System Administration and Configuration Guide .......................... 86 A2 52CDFlowBus UNIX COBOL Programmer's Guide ........................................... 86 A2 53CDFlowBus Application Administration and Integration Guide .......................... 86 A2 54CDFlowBus Configuration Tool User's Guide ................................................... 86 A2 55CDFlowBus UNIX C Programmer's Guide........................................................ 86 A2 60CDFlowBus GCOS 8 COBOL Programmer's Guide ......................................... 86 A2 61CDFlowBus GCOS 7 COBOL Programmer's Guide ......................................... 86 A2 63CDFlowBus UNIX Export C Programmer's Guide..............................................86 A2 03CZFlowBus MQ Gateway Extensions Programmer's Guide ..............................86 A2 05CZFlowBus Local Queuing User's Guide ..........................................................86 A2 07CZFlowBus MVS COBOL Programmer's Guide................................................86 A2 08CZ

On-line help is available for the FlowBus Administration Tool.

The other documents referenced include:

TUXEDO Product Overview......................................................................... 86 A2 49ATTUXEDO Application Development Guide.................................................... 86 A2 51ATTUXEDO Reference Manual ........................................................................ 86 A2 61AT


6 86 A2 63CD Rev01

86 A2 63CD Rev01 vii

Table of Contents

1. The Application Development Route ....................................................... 1-1

1.1 WHAT THIS CHAPTER IS ABOUT ........................................................................ 1-1

1.2 OVERVIEW ............................................................................................................ 1-2

1.3 APPLICATIONS ..................................................................................................... 1-3

1.3.1 New Applications .................................................................................................. 1-31.3.2 Existing Applications ........................................................................................... 1-31.3.3 Wrappers ............................................................................................................... 1-31.3.4 GCOS 7 Applications ............................................................................................ 1-4

1.4 DELIVERY POINTS AND MESSAGE BASE TYPES ............................................. 1-5

1.4.1 Delivery Points ...................................................................................................... 1-51.4.2 Message Base Types ............................................................................................ 1-6

1.5 RETURN CODES AND ERROR HANDLING .......................................................... 1-7

1.6 C STRING HANDLING IN COBOL PROGRAMS ................................................... 1-8

2. High-level Interactions with FlowBus ...................................................... 2-1


2.2 HIGH-LEVEL INTERACTIONS ON CLIENT APPLICATIONS ............................... 2-1

2.2.1 How to code a high-level PUT on a client ........................................................... 2-22.2.2 How to code a high-level GET on a client ........................................................... 2-2


viii 86 A2 63CD Rev01

2.2.3 How to code a high-level CALL ............................................................................ 2-3

2.3 HIGH-LEVEL INTERACTIONS ON SERVER APPLICATIONS .............................. 2-4

2.3.1 How to code a high-level PUT on a server .......................................................... 2-42.3.2 How to code a high-level GET on a server .......................................................... 2-52.3.3 How to code a high-level SERVE ......................................................................... 2-6

3. Low-level Interactions with FlowBus ....................................................... 3-1


3.2 THE XATMI-CONFORMANT ROUTINES .............................................................. 3-2

3.3 LOW-LEVEL INTERACTIONS ON CLIENT APPLICATIONS ................................ 3-3

3.3.1 High-level tasks using low-level routines ........................................................... 3-4

3.4 LOW-LEVEL INTERACTIONS ON SERVER APPLICATIONS .............................. 3-5

3.4.1 High-level tasks using low-level routines ........................................................... 3-6

4. Transactions ..................................................................................................... 4-1


4.2 TRANSACTIONS ON CLIENT APPLICATIONS .................................................... 4-2

4.3 TRANSACTIONS UNDER GCOS 7 ON SERVER APPLICATIONS ....................... 4-3

5. Message Classification ................................................................................. 5-1


5.2 HOW TO CREATE A MESSAGE CLASSIFICATION ............................................. 5-2

5.2.1 Message Classification Skeleton ......................................................................... 5-3

Table of Contents

86 A2 63CD Rev01 ix

6. Building Clients and Servers ...................................................................... 6-1


6.2 HOW TO BUILD BABC7 AND BABS7 ................................................................... 6-2

6.2.1 Using Message Classification .............................................................................. 6-2


x 86 A2 63CD Rev01

Appendices

A. The FlowBus GCOS 7 COBOL API ............................................................ A-1

A.1 WHAT THIS APPENDIX CONTAINS ...................................................................... A-1

A.2 XATMI-CONFORMANT ROUTINES ....................................................................... A-2

A.2.1 Data Types ............................................................................................................ A-2A.2.2 Message Base Types ............................................................................................ A-2A.2.3 Message Length .................................................................................................... A-2A.2.4 Delivery Points ...................................................................................................... A-2A.2.5 Typed Records ...................................................................................................... A-3A.2.6 COBOL Language Definitions .............................................................................. A-4A.2.7 FlowBus API State Transitions ............................................................................ A-9

A.3 HIGH-LEVEL ROUTINES ....................................................................................... A-10

A.3.1 Routine Usage ....................................................................................................... A-11A.3.2 The DATA-BUFFER parameter ............................................................................. A-12A.3.3 Returned Messages .............................................................................................. A-12

A.4 HOW TO COMPILE YOUR FLOWBUS TPRS ....................................................... A-14

A.4.1 Configuring the Application Loader .................................................................... A-15

A.5 ROUTINE REFERENCES ...................................................................................... A-16

A.5.1 ABACALL .............................................................................................................. A-16A.5.2 ABCALL ................................................................................................................. A-22A.5.3 ABGETRPLY ......................................................................................................... A-29A.5.4 ABINIT ................................................................................................................... A-36A.5.5 ABRETURN ............................................................................................................ A-39A.5.6 ABSVCSTART ....................................................................................................... A-44A.5.7 ABTERM ................................................................................................................ A-48A.5.8 CALL ...................................................................................................................... A-50A.5.9 GET ........................................................................................................................ A-54A.5.10 GETRETURN ......................................................................................................... A-58A.5.11 GETSVCSTART ..................................................................................................... A-62A.5.12 PUT ........................................................................................................................ A-65A.5.13 PUTRETURN ......................................................................................................... A-69A.5.14 PUTSVCSTART ..................................................................................................... A-73

Table of Contents

86 A2 63CD Rev01 xi

A.5.15 SERVERETURN..................................................................................................... A-76A.5.16 SERVESTART ....................................................................................................... A-80

B. Application Instances .................................................................................... B-1

B.1 WHAT THIS APPENDIX IS ABOUT ....................................................................... B-1

B.2 APPLICATION INST ANCES .................................................................................. B-2

B.2.1 Application Instance Identifier ............................................................................. B-3B.2.2 Application Profile ................................................................................................ B-3B.2.3 Run Command ...................................................................................................... B-3B.2.4 Run Server Group ................................................................................................. B-4B.2.5 Delivery Point Mappings ...................................................................................... B-5

C. The Example Application (sampleapp) ................................................... C-1

C.1 WHAT THIS APPENDIX IS ABOUT ....................................................................... C-1

C.2 THE EXAMPLE APPLICATION (SAMPLEAPP) ..................................................... C-2

C.2.1 Network Model Symbols ....................................................................................... C-2C.2.1.1 Sampleapp Network Models.................................................................................... C-2

C.2.2 UNIX sampleapp Directory Structure ................................................................... C-7C.2.3 GCOS 7 sampleapp Directory Structure .............................................................. C-7C.2.4 GCOS 7 sampleapp clients .................................................................................. C-7C.2.5 GCOS 7 sampleapp Servers ................................................................................. C-8C.2.6 GCOS 7 sampleapp Data Files ............................................................................. C-9C.2.7 UNIX sampleapp Transformation Server ............................................................. C-9C.2.8 UNIX sampleapp Queues ...................................................................................... C-9C.2.9 How to Build sampleapp on UNIX ........................................................................ C-10C.2.10 How to Build sampleapp on GCOS 7 ................................................................... C-13C.2.11 How to Run the UNIX components necessary for sampleapp ........................... C-15C.2.12 How to Run sampleapp on GCOS 7 ..................................................................... C-16C.2.13 How to Delete sampleapp on UNIX ...................................................................... C-17

Glossary .............................................................................................................................. g-1

Index .............................................................................................................................. i-1


xii 86 A2 63CD Rev01

Illustrations

Figures

3-1 FlowBus API Routine Structure for the Client Side of an Exchange......................... 3-33-2 FlowBus API Routine Structure for the Server Side of an Exchange ....................... 3-54-1 TX and FlowBus API Routine Structure for the Client Side of an Exchange ............ 4-2C-1 Network Model Symbols ......................................................................................... C-3C-2 Network Model using the Message Transformation Service (sampleapp-host) ........ C-5C-3 Network Model without the Message Transformation Service(sampleapp-host2)..... C-6C-4 Directory structure under sampleapp....................................................................... C-7

86 A2 63CD Rev01 1-1

1. The Application Development Route

1.1 WHAT THIS CHAPTER IS ABOUT

This chapter outlines the steps that you must take in order to make applications interactover FlowBus. This chapter introduces important concepts and provides an overview ofthe process. See the remaining chapters of this guide for full details.

The chapter covers these topics:

• Overview

• Applications

• Delivery points and message base types

• Return codes and error handling

• C string handling in COBOL programs


1-2 86 A2 63CD Rev01

1.2 OVERVIEW

The following steps are necessary in order to program applications that will interact overFlowBus:

• Determine the tasks required to meet business requirements

• Identify the following:

- The application that will do each task

- Which applications are clients and which are servers

- The kind of exchange between each pair of applications that interact(notification, query/response)

- The format of messages that each application uses

• Create any new applications that are required

• Decide for each existing application whether to upgrade it or create a wrapper

• Identify the points at which each application must pass a message to FlowBus

• Add FlowBus API routines to the application or wrapper as appropriate

• Compile, link and test the programs

The applications do not refer to each other in any way. The FlowBus configurationdetermines the route of each message. FlowBus adds messages to a queue as required.It also transforms them into the format required by the recipient application.

The Application Development Route

86 A2 63CD Rev01 1-3

1.3 APPLICATIONS

An application is any processing that FlowBus sees as one set of delivery points.Applications use FlowBus API routines to pass messages to FlowBus. You can includethese routines in new or existing applications. Alternatively, you can create a specialapplication called a wrapper to contain the same routines for an existing application.

Each application has delivery points that are defined by the application code. Eachdelivery point must also be configured in FlowBus.

1.3.1 New Applications

You can design new applications to interact with existing applications over FlowBus. Forexample, you might design a new user interface to query an existing database. Asbusiness requirements develop, you can also design applications that interact with eachother over FlowBus. In either case, you design the application to include FlowBus APIroutines that pass a message to FlowBus. FlowBus then passes the message to anotherapplication for processing.

1.3.2 Existing Applications

You can include FlowBus API routines in existing applications. You do this in order to:

• Use processing from other applications (act as a client).

• Do processing for other applications (act as a server).

You must identify the appropriate point in the application to pass a message to or fromFlowBus. You must also ensure that all errors from the FlowBus API routines are handledappropriately.

1.3.3 Wrappers

A wrapper is a separate application that includes an existing application. The wrapperintercepts calls in the wrapped application. It passes messages to FlowBus just as if theFlowBus API routines were in the original application.

You use a wrapper when you cannot update the application directly, for example, whenthe source is not available.


1-4 86 A2 63CD Rev01

1.3.4 GCOS 7 Applications

If you need to make a GCOS 7 application interact over FlowBus, you must either createa wrapper or include appropriate FlowBus API routines in the GCOS 7 application.

Although some FlowBus API routines have similar names to TUXEDO API routines, youshould always be aware of differences in functionality. For example, the FlowBus APIroutines refer to delivery points which get mapped to service names whereas theTUXEDO API routines refer to service names directly.


86 A2 63CD Rev01 1-5

1.4 DELIVERY POINTS AND MESSAGE BASE TYPES

The application integrator designs the FlowBus configuration to meet businessrequirements. The FlowBus configuration consists of one or more network models, eachof which defines the routing of messages between a given set of applications.

As application programmer, you need to refer to the following:

• The delivery points that are configured on each application in FlowBus

• The message formats (message base types) that are associated with each deliverypoint

Because the application code does not refer to other applications, you do not need toupdate it when different message routing is required. Routing is handled entirely in theFlowBus configuration.

1.4.1 Delivery Points

Applications send and receive messages at delivery points, which serve to grouptogether messages in logical data streams. A client delivery point initiates aninteraction with FlowBus. A server delivery point handles a message when FlowBusrequires it to do so. In addition, each delivery point of either type is one of the following:

• PUTA PUT delivery point passes messages on to FlowBus.

• GETA GET delivery point obtains messages from FlowBus.

• CALLA CALL delivery point passes messages on to FlowBus and obtains the reply to eachmessage.

• SERVEA SERVE delivery point obtains messages from FlowBus and sends a reply to eachmessage.


1-6 86 A2 63CD Rev01

Each delivery point has a name that is unique to the application.

The FlowBus API includes routines that process messages at each of the above types ofdelivery points. It also includes low-level routines that let you do more sophisticatedprocessing of messages at delivery points. You pass a message to FlowBus by usingFlowBus API routines to specify the following:

• The content of the message

• The name of the delivery point at which it is passed on to FlowBus

• The message base type of the message (see the section Message Base Types in thischapter)

The type of a delivery point is determined in the FlowBus configuration. FlowBus will onlyhandle messages at a given delivery point in the way configured for the delivery point.

1.4.2 Message Base Types

Each delivery point is configured to handle messages of one or more specified messagebase types. A message base type represents a message format. If the message passedto FlowBus is to be transformed, the message base type must specifically refer to itsformat. If the message does not need to be transformed, the message base type neednot refer to a specific format.

The application integrator defines message base types and associates each with one ormore delivery points. You can only use the FlowBus API to pass messages of the basetypes that are configured for a delivery point. If the application tries to pass a message ofanother base type, FlowBus returns an error.


86 A2 63CD Rev01 1-7

1.5 RETURN CODES AND ERROR HANDLING

The FlowBus API routines return codes that report the following types of conditions:

• The routine has succeeded

• There is an error in the way the routine is used

• The FlowBus configuration does not match the coding in the application (for example,a delivery point named in the code does not exist in the configuration)

• The current transaction has failed

• The server application has returned an error

• There has been a system failure

The return codes from FlowBus API routines are normally the same as those fromTUXEDO transactions. Errors that involve services may refer either to the delivery pointon the current application or to the service to which the message is routed. See thereturn codes and errors described for each routine in Appendix A of this guide for details.

The application should handle error messages in a way that does not assume that theycome from any particular application. This is because the FlowBus configuration canroute messages to a different application at any time. See the section Error Messages inAppendix A of this guide for details.


1-8 86 A2 63CD Rev01

1.6 C STRING HANDLING IN COBOL PROGRAMS

A C string, in COBOL terms, is a variable length data item containing zero or morecharacters whose value is not LOW-VALUE (X"00") terminated by one character whosevalue is LOW-VALUE.

If a COBOL program calls, or is called by, a C function which returns a string, care isneeded when manipulating the string in the COBOL program because the LOW-VALUEterminator must be ignored.

This consideration is necessary if your COBOL application uses COBOL transformationrules and/or COBOL message classification programs. Also, if your application consistsof a mixture of COBOL and C clients and/or servers.

A data item used to contain a string may be defined in several ways depending on useand preference. For example:

01 STRING1 PIC X(12) VALUE LOW-VALUE.

01 STRING2. 05 FILLER PIC X(12) VALUE LOW-VALUE.

01 STRING3. 05 STRING3-DATA PIC X(11) VALUE LOW-VALUE. 05 FILLER PIC X VALUE LOW-VALUE.

The above definitions all define a data record long enough to hold a string with amaximum length of 11 characters.

01 STRING4. 05 STRING4-CHAR PIC X OCCURS 11 TIMES VALUE LOW-VALUE. 05 FILLER PIC X VALUE LOW-VALUE.

The above definition allows access to individual characters through the use of a subscriptor index.

If the length of the string is variable, a definition such as that given for STRING1 couldbe suitable. If the value of the NULL-terminated string is "customer", the comparisoncould be coded, for example, as:

. . . IF STRING3-DATA = "custdetails" . . .


86 A2 63CD Rev01 1-9

If the length of the string is a fixed value, a definition such as that given for STRING3could be suitable. If the value of the NULL-terminated string is "custdetails", thecomparison could be coded, for example, as:

. . . IF STRING1(1:8) = "customer" . . .

where 8 corresponds to the number of characters preceding the LOW-VALUE characterin the string.


1-10 86 A2 63CD Rev01

86 A2 63CD Rev01 2-1

2. High-level Interactions with FlowBus


This chapter tells you how you use FlowBus API routines to program high-levelinteractions with FlowBus. These interactions use FlowBus API routines that corresponddirectly to the exchange that occurs at each type of delivery point.

See the introduction to Appendix A of this guide for full information about the FlowBusAPI.


• High-level interactions on client applications

• High-level interactions on server applications

2.2 HIGH-LEVEL INTERACTIONS ON CLIENT APPLICATIONS

An application that acts as a client always initiates an interaction with FlowBus. A clientapplication can have the following delivery points:

• One or more client PUT delivery pointsThe application actively passes a notification message to FlowBus at a PUT deliverypoint.

• One or more client GET delivery pointsThe application actively obtains a notification message from FlowBus at a GETdelivery point.

• One or more client CALL delivery pointsThe application actively passes messages on to FlowBus and obtains the response ata CALL delivery point.

Each delivery point must be:

• Named in the application code

• Programmed to do the appropriate task


2-2 86 A2 63CD Rev01

You can use the high-level FlowBus API routines PUT, GET and CALL at these deliverypoints to do their specified tasks simply.

Each delivery point must also be:

• Named to FlowBus

• Defined as PUT, GET or CALL to FlowBus

• Configured to send any message base types sent (if it is a PUT or CALL deliverypoint)

• Configured to receive any message base types received (if it is a GET or CALLdelivery point)

2.2.1 How to code a high-level PUT on a client

The PUT routine handles all of the interaction with FlowBus required to send a messageat a PUT delivery point. You need to specify the following in the PUT routine:

• The name of the delivery point

• The message base type of the message to be sent to FlowBus


• The length of the message

• The maximum length of any reply error message

The delivery point and the message base type must be those defined to FlowBus. Thecontent of the message can be derived in any appropriate way.

The PUT routine outputs the following:

• The status of the PUT routine

See Appendix A of this guide for full details of the PUT routine and an example of how tocode a high-level PUT.

2.2.2 How to code a high-level GET on a client

The GET routine handles all of the interaction with FlowBus required to obtain amessage at a GET delivery point. You need to specify the following in the GET routine:


• The message base type of the message to be obtained from FlowBus

• The maximum length of the reply message

High-level Interactions with FlowBus

86 A2 63CD Rev01 2-3

The delivery point and the message base type must be those defined to FlowBus.

The GET routine outputs the following:

• The actual message base type of the message obtained from FlowBus



• The status of the GET routine

See Appendix A of this guide for full details of the GET routine and an example of how tocode a high-level GET.

2.2.3 How to code a high-level CALL

The CALL routine handles all of the interaction with FlowBus required to do the following:

• Pass a query message to call a service to FlowBus at a CALL delivery point

• Obtain a response message at the same delivery point

You need to specify the following in the CALL routine:



• The content of the outgoing message


• The maximum length of the reply message

The delivery point and the message base types must be those defined to FlowBus. Thecontent of the message can be derived in any appropriate way.

The CALL routine outputs the following:



• The content of the incoming message

• The status of the CALL routine

See Appendix A of this guide for full details of the CALL routine and an example of howto code a high-level CALL .


2-4 86 A2 63CD Rev01

2.3 HIGH-LEVEL INTERACTIONS ON SERVER APPLICATIONS

An application that acts as a server waits for FlowBus to initiate an interaction. A serverapplication can have the following delivery points:

• One or more server PUT delivery pointsThe application passes a notification message when requested by FlowBus at a PUTdelivery point.

• One or more server GET delivery pointsThe application obtains a notification message when FlowBus delivers one at a GETdelivery point.

• One or more server SERVE delivery pointsThe application obtains messages from FlowBus and returns the response message ata SERVE delivery point.

Each delivery point must be named in the application code and programmed to do theappropriate task. It must also be named and defined as PUT, GET or SERVE toFlowBus. In addition, the message base type or types referenced at a delivery point mustbe defined to FlowBus and associated with the delivery point.

You can use the high-level FlowBus API routines, for example PUTSVCSTART andPUTRETURN, at these delivery points to do their specified tasks simply. Each exchangeat a delivery point on a server is a service that consists of the following sequence ofroutines:

• A routine to start the serviceThe service is given a message sent from the client.

• A routine to return from the serviceThe service replies to the client if required.

An error is returned if one of these routines is missing.

2.3.1 How to code a high-level PUT on a server

A PUT task on a server sends a notification message over FlowBus in response to arequest from a client GET task.

A PUT task on a server consists of two stages:

• A PUTSVCSTART routine that obtains the request at the start of a PUT service

• A PUTRETURN routine that passes a message back to the client from a PUT deliverypoint

You need to specify the following in the PUTSVCSTART routine:


The PUTSVCSTART routine outputs an empty incoming message and a return status.

You need to specify the following in the PUTRETURN routine:

High-level Interactions with FlowBus

86 A2 63CD Rev01 2-5


• The content of the outgoing message


The delivery point and the message base type must be those defined to FlowBus. Thecontent of the message can be derived in any appropriate way.

See Appendix A of this guide for full details of the PUTSVCSTART and PUTRETURNroutines and an example of how to code a high-level PUTSVCSTART andPUTRETURN.

2.3.2 How to code a high-level GET on a server

A GET task on a server receives a notification message over FlowBus from a client PUTtask.

A GET task on a server consists of two stages:

• A GETSVCSTART routine that obtains the request at the start of the GET service

• A GETRETURN routine that passes a message back to the client from a GET deliverypoint

You need to specify the following in the GETSVCSTART routine:


• The maximum length of the incoming message

The delivery point must be one of those defined to FlowBus.

The GETSVCSTART routine outputs the following:




The message base type must be defined to FlowBus.

You need to specify the following in the GETRETURN routine:

• The content of any outgoing error message

• The length of the error message.

See Appendix A of this guide for full details of the GETSVCSTART and GETRETURNroutines and an example of how to code a high-level GETSVCSTART andGETRETURN.


2-6 86 A2 63CD Rev01

2.3.3 How to code a high-level SERVE

A SERVE task on a server receives a query message over FlowBus from a client CALLtask. It returns a response message to the same client CALL task.

A SERVE task on a server consists of two stages:

• A SERVESTART routine that starts the SERVE service. It handles all of theinteraction with FlowBus required to obtain a message at a SERVE delivery point.

• A SERVERETURN routine that completes the SERVE service. It handles all of theinteraction with FlowBus required to send a message at the same delivery point.

You need to specify the following in the SERVESTART routine:


• The maximum length of the incoming message

The SERVESTART routine outputs the following:

• The message base type of the message obtained from FlowBus

• The length of the incoming message


• The status of the SERVESTART routine

You need to specify the following in the SERVERETURN routine:

• The message base type of the message to be passed on to FlowBus



The delivery point and the message base types must be those defined to FlowBus. Thecontent of the message can be derived in any appropriate way.

See Appendix A of this guide for full details of the SERVESTART and SERVERETURNroutines and an example of how to code a high-level SERVESTART andSERVERETURN.

86 A2 63CD Rev01 3-1

3. Low-level Interactions with FlowBus


This chapter tells you how you use FlowBus API routines to program low-levelinteractions with FlowBus. These interactions use FlowBus API routines that are X/OPENXATMI-conformant. These routines allow you to code exchanges, at each type ofdelivery point, that are controlled in more complex ways.

See the introduction to Appendix A of this guide for full information about the FlowBusAPI.


• The XATMI-conformant routines

• Low-level interactions on client applications

• Low-level interactions on server applications


3-2 86 A2 63CD Rev01

3.2 THE XATMI-CONFORMANT ROUTINES

The FlowBus API uses the following XATMI-conformant routines to exchange messageswith FlowBus:

• ABCALLThis routine sends a synchronous call on to FlowBus and waits for a response.

• ABACALLThis routine sends an asynchronous call on to FlowBus. It must be followed by anABGETRPLY routine.

• ABGETRPLYThis routine obtains an asynchronous reply to an ABACALL routine from FlowBus.

• ABSVCSTARTThis routine obtains a call from FlowBus and starts a service. It must be followed byan ABRETURN routine.

• ABRETURNThis routine sends a reply to a call obtained by an ABSVCSTART routine on toFlowBus.

• ABINITThis optional routine connects the application to FlowBus.

• ABTERMThis optional routine disconnects the application from FlowBus.

You must use these routines in specific sequences for client and server applications. Seethe sections Low-level Interactions on Client Applications and Low-level Interactions onServer Applications of this chapter for details.

If ABINIT is not specified explicitly, the application is connected to FlowBusautomatically by the first AB... routine which requires a connection.

If ABTERM is not specified explicitly, the application will remain connected to FlowBus.

The low-level FlowBus API routines enable you to program applications in a moreflexible way than is possible when using the high-level routines described in the chapterHigh-level Interaction with FlowBus of this guide. You can use the low-level routines toprogram all of the high-level tasks. However, it is sometimes necessary to program morethan one low-level routine for the equivalent functionality provided by one high-levelroutine.

For example, the low-level equivalent of a high-level CALL routine in a client applicationcan be programmed as an ABACALL routine followed by an ABGETRPLY routine toobtain the response. This method provides the capability to program additionalprocessing between the ABACALL and the ABGETRPLY routines. The response to thecall is co-ordinated with the call when the ABGETRPLY routine obtains it.

See Appendix A of this guide for full details of all FlowBus API routines.

Low-level Interactions with FlowBus

86 A2 63CD Rev01 3-3

3.3 LOW-LEVEL INTERACTIONS ON CLIENT APPLICATIONS

Client applications can use FlowBus API routines in the following sequence as the basisfor exchanges with FlowBus:

AB IN IT

A BC A LLAB AC A LL

AB G E TR PLY

AB TE RM

Figure 3-1. FlowBus API Routine Structure for the Client Side of an Exchange

Programs that use these routines must obey the following rules:

• An ABINIT routine must occur before any other routineThe ABINIT routine allocates resources necessary for communication with FlowBus. Itdeclares the presence of the application to FlowBus.

• The ABACALL routine must occur before the ABGETRPLY routineEvery ABACALL routine must have a corresponding ABGETRPLY routine

• An ABTERM routine must occur after all the other routines required for the exchangeThe ABTERM routine de-allocates the resources allocated for communication withFlowBus.


3-4 86 A2 63CD Rev01

An exchange with FlowBus can be programmed in one of the following ways:

• With an ABCALL routineThe ABCALL routine makes a synchronous call, during which the application isblocked waiting for the reply.

• With an ABACALL routine and a corresponding ABGETRPLY routine.The ABACALL routine makes an asynchronous call. The application carries onprocessing and obtains the reply with the ABGETRPLY routine.

ABACALL routines can be interleaved. For example, several ABACALL routines canoccur together, followed by the corresponding ABGETRPLY routines. FlowBus ensuresthat an ABACALL routine is co-ordinated with its corresponding ABGETRPLY routine.

3.3.1 High-level tasks using low-level routines

You can use an ABCALL routine to code an exchange at all types of delivery points on aclient application. When the ABCALL routine passes a message at a PUT delivery point,the incoming message must be empty. When the ABCALL routine obtains a message ata GET delivery point, the outgoing message must be empty.

The following table illustrates the content of the relevant parameters to the ABCALLroutine at each type of delivery point. Appendix A of this guide describes the ABCALLroutine in full.

Delivery point IDATA-REC ODATA-REC

PUT Outgoing message content Set to SPACES

GET Set to SPACES Incoming message content

CALL Outgoing message content Incoming message content

You can also use an ABACALL routine followed by an ABGETRPLY routine to code anexchange at a CALL delivery point. In this case, the application can continue processingand obtain the reply at an appropriate point.

See Appendix A of this guide for full details of the ABINIT , ABCALL , ABACALL ,ABGETRPLY and ABTERM routines and examples of coding calls to the ABINIT ,ABCALL , ABACALL , ABGETRPLY and ABTERM routines.

Low-level Interactions with FlowBus

86 A2 63CD Rev01 3-5

3.4 LOW-LEVEL INTERACTIONS ON SERVER APPLICATIONS

Server applications, when invoked by a client over FlowBus, can use FlowBus APIroutines in the following sequence to exchange messages with FlowBus:

A B SV C STA R T

AB C ALLAB A CA LL

AB G E TR PLY

AB R ETU R N

Processing as a clien t

O nce fo r each service invocation

Figure 3-2. FlowBus API Routine Structure for the Server Side of an Exchange

Programs that use these routines must obey the following rules:

• An ABSVCSTART routine must occur at the start of every service

• An ABRETURN routine must occur at the end of every service

Any processing required can occur in a service. A service provider may also act as aclient in other exchanges with FlowBus. The routines ABCALL, ABACALL andABGETRPLY in Figure 3-2 represent this possibility.


3-6 86 A2 63CD Rev01

3.4.1 High-level tasks using low-level routines

You can use an ABSVCSTART routine followed by an ABRETURN routine to code anexchange at all types of delivery points on a server application. When the applicationpasses a message at a PUT delivery point, the ABSVCSTART routine must obtain anempty message. When the application obtains a message at a GET delivery point, theABRETURN routine must pass an empty message.

The following table illustrates the content of the relevant parameters to theABSVCSTART and ABRETURN routine at each type of delivery point. Appendix A ofthis guide describes the parameters of the routines in full.

Delivery point ABSVCSTART DATA-REC ABRETURN DATA-REC

PUT Set to SPACES Outgoing message content

GET Incoming message content Set to SPACES

SERVE Incoming message content Outgoing message content

See Appendix A of this guide for full details of the ABSVCSTART and ABRETURNroutines and examples of coding calls to the ABSVCSTART and ABRETURN routines.

86 A2 63CD Rev01 4-1

4. Transactions


This chapter describes the rules which you must follow to use the FlowBus API routinesin transactions. The FlowBus API routines described in this chapter are XATMIconformant. They are the same as the TUXEDO routines of the same name, but you canuse them on any permitted platform.


• Client applications

• Server applications


4-2 86 A2 63CD Rev01

4.2 TRANSACTIONS ON CLIENT APPLICATIONS

Client applications can use FlowBus API routines interleaved with TUXEDO routines todo the following under transactional control:

• Call a TUXEDO service

• Process the reply

The sequence of routines that do this is shown in Figure 4-1. In Figure 4-1, the FlowBusAPI routines shown in Figure 3-1 are shown shaded. The interleaved TUXEDO routinesare unshaded.

TX BEGIN

TXCOM MIT TXROLLBACK

ABINIT

ABACALL

ABGETRPLY

ABCALL

ABTERM

Figure 4-1. TX and FlowBus API Routine Structure for the Client Side of an Exchange

Note that these TUXEDO routines are meaningless if the services requested are locatedon the same or another GCOS application.

The TXCOMMIT and TXROLLBACK routines only affect resources updated by TUXEDOtransactional services. TDS resources are not affected by theses routines.

Transactions

86 A2 63CD Rev01 4-3

Client applications that use TUXEDO routines must obey the following rules:

• Each transaction is started by TXBEGIN and either successfully ended by aTXCOMMIT or aborted by a TXROLLBACK

See the TUXEDO documentation for full information about programming transactionsunder TUXEDO, and the Section COBOL Language Definitions in the appendix entitledThe FlowBus GCOS 7 COBOL API in this guide.

4.3 TRANSACTIONS UNDER GCOS 7 ON SERVER APPLICATIONS

Server TDS transactions cannot be executed under TUXEDO transactional control. Forexample a TUXEDO client cannot request a TDS transaction rollback by calling theroutine TXROLLBACK.


4-4 86 A2 63CD Rev01

86 A2 63CD Rev01 5-1

5. Message Classification


This chapter tells you about message classification.

The chapter covers this topic:

How to Create a Message Classification


5-2 86 A2 63CD Rev01

5.2 HOW TO CREATE A MESSAGE CLASSIFICATION

A message classification is a routine that is used by FlowBus to perform data dependentrouting.

To create a message classification, you must do the following steps:

• Decide how to divide the messages represented by a message base type into usefulgroups and give each group a name

• Create a message sub-type for each group name

• Make the message sub-types available

• Code the message classification as a C function or as a COBOL program. The nameof the C function or COBOL program must be the same as the message sub-type.

The C function or COBOL program must be coded on a UNIX computer .

• Create a network model using the FlowBus Configuration Tool. Use the message sub-types in place of a message base type in order to route messages of each sub-type todifferent destinations.

• Compile and link the C function (babclassif.c) generated when the message sub-typesare made available, together with all the classification routines, into all the applicationsthat perform data dependent routing when they send messages

The C function babclassif.c is generated in the directory containing the configurationdatabase.

Only applications that send messages using data dependent routing need to be linkedwith babclassif.c and all the classification routines. It is not necessary to linkbabclassif.c and all the classification routines into the applications which receive themessages.

For non-UNIX applications, babcl assif.c and all the classificat ion routinesshould be linked into the BA BC7 client and BABS7 server that comm unicatewith the remote computer. Details of linking BABC7 and BABS7 can be found in thechapter Building Clients and Servers of this guide.

For example, the message base type DEPOSIT could be divided into two message sub-types, SMALL-DEPOSIT and LARGE-DEPOSIT, where SMALL-DEPOSIT representsvalues less than 10 000 and LARGE-DEPOSIT represents values greater than or equalto 10 000.

Message Classification

86 A2 63CD Rev01 5-3

5.2.1 Message Classification Skeleton

Skeleton code for a message classification COBOL program is shown below:

IDENTIFICATION DIVISION.PROGRAM-ID. <Replace with SUB-MESSAGE-TYPE name>.

ENVIRONMENT DIVISION.CONFIGURATION SECTION.WORKING-STORAGE SECTION.LINKAGE SECTION.01 MESSAGE-BASE-TYPE PIC X(16).01 MESSAGE-SUB-TYPE PIC X(16).01 MESSAGE-BUFFER PIC X(10000).01 RETURN-CLASSIFY-REQUEST PIC S9(9) COMP-5. 88 CLASSIFIED-MESSAGE VALUE 0. 88 NOT-CLASSIFIED-MESSAGE VALUE -1.

PROCEDURE DIVISION USING MESSAGE-BASE-TYPE MESSAGE-SUB-TYPE MESSAGE-BUFFER RETURN-CLASSIFY-REQUEST.main-01.* IF <test whether message in MESSAGE-BUFFER is a MESSAGE-SUB-TYPE> THEN SET CLASSIFIED-MESSAGE TO TRUE. ELSE SET NOT-CLASSIFIED-MESSAGE TO TRUE.

EXIT PROGRAM.


5-4 86 A2 63CD Rev01

86 A2 63CD Rev01 6-1

6. Building Clients and Servers


This chapter tells you how to link applications that include FlowBus API routines.


How to Build BABC7 and BABS7


6-2 86 A2 63CD Rev01

6.2 HOW TO BUILD BABC7 AND BABS7

FlowBus applications are comprised of TUXEDO clients and servers which have beenlinked with the FlowBus libraries and objects.

GCOS 7 applications are represented by a TUXEDO client and server whichcommunicate with the GCOS 7 computer. They perform the FlowBus API calls on theUNIX computer on behalf of the GCOS 7 applications. The TUXEDO client is calledBABC7. The TUXEDO server is called BABS7.

Please refer to appendix A for information on building GCOS 7 FlowBus TPRs.

Make files are provided on UNIX in $BAB_ROOTDIR/bin for building BABC7 and BABS7($BAB_ROOTDIR is the UNIX environment variable whose value is the absolutepathname of the directory into which the FlowBus software was installed).

BABC7 is built with the following command:

make -f $BAB_ROOTDIR/bin/BABC7.mk

BABS7 is built with the following command:

make -f $BAB_ROOTDIR/bin/BABS7.mk

Please refer to System Administrator UNIX Environment in the FlowBus SystemAdministration and Configuration Guide for required environment setting.

6.2.1 Using Message Classification

Clients and servers that need to use message classification to perform data dependentrouting are linked in a similar way to other clients and servers. The difference being theaddition of the C function (babclassif.c) which is generated automatically each time amessage sub-type is made available and the addition of classification rule objects.

Clients which use message classification are built with the following commands:

CLASSIFY="babclassif.c <user classification functions>"export CLASSIFYmake -f $BAB_ROOTDIR/bin/BABC7.mk

Servers which use message classification are built with the following command:

CLASSIFY="babclassif.c <user classification functions>"export CLASSIFYmake -f $BAB_ROOTDIR/bin/BABS7.mk

Where:

<user classification functions> is the name(s) of the classification rule sourcefiles.

86 A2 63CD Rev01 A-1

A. The FlowBus GCOS 7 COBOL API

A.1 WHAT THIS APPENDIX CONTAINS

This appendix contains reference documentation for the routines in the FlowBus GCOS 7COBOL API.

The rest of this introduction contains guide-lines for COBOL programming using theFlowBus API. Each section of the rest of this appendix documents one routine.


A-2 86 A2 63CD Rev01

A.2 XATMI-CONFORMANT ROUTINES

This section tells you about some techniques for using the routines in the FlowBus APIthat conform to the XATMI standard. These routines are marked with an asterisk (*) inthe reference pages of this appendix. The routines used for the transaction managementinterface (TXBEGIN, TXCOMMIT and TXROLLBACK) are not documented in thisappendix. See the TUXEDO documentation.

A.2.1 Data Types

Data types hide the way in which the data is actually stored. Each data type used by theFlowBus API is defined for each language in a COPY file supplied with the FlowBus API.The data types defined in this file contain a description of the data structure and thecontent of each item in the data structure. See the section COBOL Language Definitionsof this appendix for details of the COBOL data structure.

A.2.2 Message Base Types

Every message that FlowBus carries has a message base type identifier. A messagebase type identifier consists of a name, for example, DEBIT. The message base typeidentifies a message format, which may be null if required.

The application integrator defines message base types to FlowBus. FlowBus handleseach message as if it is in the format identified by its message base type.

A.2.3 Message Length

Message data used in a particular format may vary in length. For example, ASCIIcharacter buffers of different lengths can be sent over FlowBus using the same messagebase type. The COBOL API routines cannot determine the length in bytes of a data itempassed as a parameter. The application code must establish the length of the data itemand store it in another variable. In general, for variable length data, the data must bestored in a fixed length data item or buffer, and the length of the data actually usedstored in another data item. This means that some of the space in the buffer may bewasted.

A.2.4 Delivery Points

Applications send and receive messages at delivery points, which serve to grouptogether messages in logical data streams. The delivery point is mapped onto the dataitem SERVICE-NAME in ABSVCDEF-REC structure.

The FlowBus GCOS 7 COBOL API

86 A2 63CD Rev01 A-3

A.2.5 Typed Records

For compatibility with ATMI, the FlowBus API adheres to the concept of typed records .A typed record consists of a pair of COBOL records:

• A data record defined in static storageThe data record contains data to be passed to another application.

• An auxiliary type record associated with the data recordThe auxiliary type record identifies the interpretation and translation rules of the datarecord as it crosses heterogeneous machine boundaries.

The auxiliary type record contains the following information:

• The type of the data record

• The sub-type of the record

• The length of the record (variable length record types require a length to be specified)

In order to send data to another application, the sending application places the data in arecord. FlowBus uses a record type with the following settings:

• The data item REC-TYPE in ABTYPE-REC structure is always set to "BAB"

• The data item SUB-TYPE in ABTYPE-REC structure must contain the message basetype

• The data item LEN in ABTYPE-REC structure contains the length of a data message

The data item LEN in ABTYPE-REC structure contains the following information:

• The number of bytes to be sent in an outgoing message at a PUT or CALL deliverypoint

• The number of bytes to move into the user's record from an incoming message at aGET or SERVE delivery point

• The number of bytes actually moved into the user's record after a successful transferfrom an incoming message

If the size of the incoming message is larger than the size specified in LEN, only LENamount of data is moved into the data area. The remaining data is discarded.


A-4 86 A2 63CD Rev01

A.2.6 COBOL Language Definitions

The following definitions are used by the FlowBus API routines. There may be extra dataitems defined for use by FlowBus internal applications in record structures. You must notrely on the size or ordering of data items. You should always access data items usingcorrect COBOL constructs.

TPSTATUS

The TPSTATUS COBOL structure is used to hold return codes.

** TPSTATUS* 05 TP-STATUS PIC S9(9) COMP-2. 88 TPOK VALUE 0. 88 TPEABORT VALUE 1. 88 TPEBADDESC VALUE 2. 88 TPEBLOCK VALUE 3. 88 TPEINVAL VALUE 4. 88 TPELIMIT VALUE 5. 88 TPENOENT VALUE 6. 88 TPEOS VALUE 7. 88 TPEPERM VALUE 8. 88 TPEPROTO VALUE 9. 88 TPESVCERR VALUE 10. 88 TPESVCFAIL VALUE 11. 88 TPESYSTEM VALUE 12. 88 TPETIME VALUE 13. 88 TPETRAN VALUE 14. 88 TPEGOTSIG VALUE 15. 88 TPERMERR VALUE 16. 88 TPEITYPE VALUE 17. 88 TPEOTYPE VALUE 18. 88 TPERELEASE VALUE 19. 88 TPEHAZARD VALUE 20. 88 TPEHEURISTIC VALUE 21. 88 TPEEVENT VALUE 22. 88 TPEMATCH VALUE 23. 88 TPEDIAGNOSTIC VALUE 24. 88 TPEMAXVAL VALUE 26. 05 TPEVENT PIC S9(9) COMP-2. 88 TPEV-NOEVENT VALUE 0. 88 TPEV-DISCONIMM VALUE 1. 88 TPEV-SENDONLY VALUE 2. 88 TPEV-SVCERR VALUE 3. 88 TPEV-SVCFAIL VALUE 4. 88 TPEV-SVCSUCC VALUE 5. 05 APPL-RETURN-CODE PIC S9(9) COMP-2.


86 A2 63CD Rev01 A-5

TXSTATUS

The TXSTATUS COBOL structure is used to hold return codes of TX routines.

** TXSTATUS* 05 TX-STATUS PIC S9(9) COMP-2. 88 TX-NOT-SUPPORTED VALUE 1. 88 TX-OK VALUE 0. 88 TX-OUTSIDE VALUE -1. 88 TX-ROLLBACK VALUE -2. 88 TX-MIXED VALUE -3. 88 TX-HAZARD VALUE -4. 88 TX-PROTOCOL-ERROR VALUE -5. 88 TX-ERROR VALUE -6. 88 TX-FAIL VALUE -7. 88 TX-EINVAL VALUE -8. 88 TX-COMMITTED VALUE -9. 88 TX-NO-BEGIN VALUE -100. 88 TX-ROLLBACK-NO-BEGIN VALUE -102. 88 TX-MIXED-NO-BEGIN VALUE -103. 88 TX-HAZARD-NO-BEGIN VALUE -104. 88 TX-COMMITTED-NO-BEGIN VALUE -109.

ABSTATUS

The ABSTATUS COBOL structure is used to hold return codes which may be returned byTUXEDO /Q when processing message queues.

ABSTATUS must follow immediately after TPSTATUS in COBOL programs as shown inthe synopsis in the section Routine Usage of this appendix.

** ABSTATUS* 88 QMEINVAL VALUE -1. 88 QMEBADRMID VALUE -2. 88 QMENOTOPEN VALUE -3. 88 QMETRAN VALUE -4. 88 QMEBADMSGID VALUE -5. 88 QMESYSTEM VALUE -6. 88 QMEOS VALUE -7. 88 QMENOTA VALUE -8. 88 QMEPROTO VALUE -9. 88 QMEBADQUEUE VALUE -10. 88 QMENOMSG VALUE -11. 88 QMEINUSE VALUE -12.


A-6 86 A2 63CD Rev01

ABTRANS

The ABTRANS COBOL structure is used to hold the address of transaction storage usedby the FlowBus API. ABTRANS must follow immediately after ABSTATUS in COBOLprograms as shown in the synopsis in the section Routine Usage of this appendix.

For TX routines, the ABTRANS COBOL structure must also follow immediately afterTXSTATUS COBOL structure.

** ABTRANS** Pointer to the transaction storage area used by FlowBus 05 FLOWBUS-TRANS-STORAGE USAGE IS POINTER.

TPSVCDEF

The TPSVCDEF COBOL structure is used by FlowBus API routines to pass settings toand from FlowBus. The value in the data item SERVICE-NAME is the name of a deliverypoint.

** TPSVCDEF* 05 COMM-HANDLE PIC S9(9) COMP-2. 05 TPBLOCK-FLAG PIC S9(9) COMP-2. 88 TPBLOCK VALUE 0. 88 TPNOBLOCK VALUE 1. 05 TPTRAN-FLAG PIC S9(9) COMP-2. 88 TPTRAN VALUE 0. 88 TPNOTRAN VALUE 1. 05 TPREPLY-FLAG PIC S9(9) COMP-2. 88 TPREPLY VALUE 0. 88 TPNOREPLY VALUE 1. 05 TPTIME-FLAG PIC S9(9) COMP-2. 88 TPTIME VALUE 0. 88 TPNOTIME VALUE 1. 05 TPSIGRSTRT-FLAG PIC S9(9) COMP-2. 88 TPNOSIGRSTRT VALUE 0. 88 TPSIGRSTRT VALUE 1. 05 TPGETANY-FLAG PIC S9(9) COMP-2. 88 TPGETHANDLE VALUE 0. 88 TPGETANY VALUE 1. 05 TPSENDRECV-FLAG PIC S9(9) COMP-2. 88 TPSENDONLY VALUE 0. 88 TPRECVONLY VALUE 1. 05 TPNOCHANGE-FLAG PIC S9(9) COMP-2. 88 TPCHANGE VALUE 0. 88 TPNOCHANGE VALUE 1. 05 TPSERVICETYPE-FLAG PIC S9(9) COMP-2. 88 TPREQRSP VALUE 0. 88 TPCONV VALUE 1.* 05 APPKEY PIC S9(9) COMP-2. 05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-2. 05 SERVICE-NAME PIC X(15). 05 FILLER PIC X.


86 A2 63CD Rev01 A-7

TPTYPE

The TPTYPE COBOL structure is used to hold a message that is sent or received at adelivery point. The value in the data item REC-TYPE is always "BAB". The SUB-TYPEdata item contains the message base type. The LEN data item indicates the amount ofdata to send and amount received. See the section Typed Records of this appendix fordetails of these data items.

** TPTYPE* 05 REC-TYPE PIC X(8). 05 SUB-TYPE PIC X(16). 05 LEN PIC S9(9) COMP-2. 88 NO-LENGTH VALUE 0. 05 TPTYPE-STATUS PIC S9(9) COMP-2. 88 TPTYPEOK VALUE 0. 88 TPTRUNCATE VALUE 1.

FLOWBUS-TRANS-STORAGE

The FLOWBUS-TRANS-STORAGE COBOL structure is used by the FlowBus API tomanage the context of the current transaction and to identify the XCP2 communicationpath to the UNIX machine running FlowBus. This structure must be declared intransaction storage of your TPR(s) and the address of it set in the pointer declared by theCOBOL copy member ABTRANS. If FLOWBUS-TRANS-STORAGE pointer ofABTRANS structure is not initialized before calling a FlowBus API routine, the routinereturns [TPEINVAL ] value in TP-STATUS in ABSTATUS-REC.

** FLOWBUS-TRANS-STORAGE* 04 BAB-XCP2-COR PIC X(12). 04 BAB-XCP2-POOL PIC X(8). 04 BAB-CTX PIC X(180).

The pointers FLOWBUS-TRANS-STORAGE declared in ABTRANS (after TPSTATUSand TXSTATUS structures), the fields BAB-XCP2-COR and BAB-XCP2-POOL must beinitialized correctly before the first FlowBus API call. The BAB-XCP2-COR and BAB-XCP2-POOL fields should be initialized to the values given in the network generationstatements XCP2COR and XCP2POOL for communicating with the UNIX machinerunning FlowBus.

01 ABSTATUS-REC. COPY TPSTATUS. Error! Reference source not found. COPY ABSTATUS. COPY ABTRANS.*01 TX-RETURN-STATUS. COPY TXSTATUS. COPY ABTRANS.*LINKAGE SECTION.01 TRANSACTION-STORAGE. COPY MY-TX-STORAGE. 02 FLOWBUS-TRANS. COPY FLOWBUS-TRANS-STORAGE.


A-8 86 A2 63CD Rev01

* MOVE "BUSCOR" TO BAB-XCP2-COR. MOVE "BUSPOOL" TO BAB-XCP2-POOL.* SET FLOWBUS-TRANS-STORAGE IN TX-RETURN-STATUS TO ADDRESS OFFLOWBUS-TRANS.* CALL "TXBEGIN" USING TX-RETURN-STATUS.* SET FLOWBUS-TRANS-STORAGE IN ABSTATUS-REC TO ADDRESS OFFLOWBUS-TRANS.* CALL "ABINIT" USING ABINFDEF-REC ABSTATUS-REC.

TPSVCRET

The TPSVCRET COBOL structure is used by the ABRETURN routine to indicate thestatus of the transaction.

** TPSVCRET* 05 TP-RETURN-VAL PIC S9(9) COMP-2. 88 TPSUCCESS VALUE 0. 88 TPFAIL VALUE 1. 88 TPEXIT VALUE 2. 05 APPL-CODE PIC S9(9) COMP-2.

ABINFDEF

The ABINFDEF COBOL structure is a part of the first parameter used by the ABINITroutine to join the application. The field SYMB-DEST-NAME has no meaning for FlowBusGCOS 7 COBOL API.

** ABINFDEF* 05 APP-INST-ID PIC X(32). 05 SYMB-DEST-NAME PIC X(8).

ABSECURITY

The ABSECURITY COBOL structure is another part of the first parameter of the ABINITroutine, but its fields have no meaning for FlowBus GCOS 7 COBOL API.

** ABSECURITY* 05 USRNAME PIC X(30) VALUE SPACES. 05 CLTNAME PIC X(30) VALUE SPACES. 05 PASSWD PIC X(30) VALUE SPACES. 05 GRPNAME PIC X(30) VALUE SPACES. 05 DATALEN PIC S9(9) COMP-2 VALUE 0.


86 A2 63CD Rev01 A-9

A.2.7 FlowBus API State Transitions

FlowBus keeps track of states for each application. It verifies that legal state transitionsoccur for the various function calls and options. The state information includes thefollowing:

• Application type (server or client)

• Initialization state (uninitialized or initialized) of the application

• Resource management state (closed or opened) of the application

• Transaction state of the application

• State of all asynchronous request/response and connection handles

When an illegal state transition is attempted, the called function fails setting TP-STATUSin ABSTATUS-REC to [TPEPROTO].


A-10 86 A2 63CD Rev01

A.3 HIGH-LEVEL ROUTINES

This section tells you about the high-level routines in the FlowBus API. These routinesare those not marked with an asterisk (*) in the reference pages of this appendix.

The high-level routines are simpler to use than the routines that conform to the XATMIstandard. Their functions correspond closely to the basic interaction at each type ofdelivery point. For example, the PUT routine passes a message of a specified base typeat a PUT delivery point.

The high-level routines are implemented as COPY files that use the following XATMI-conformant calls:

High-level routine XATMI routine called

PUT ABCALLGET ABCALLCALL ABCALL

PUTSVCSTART ABSVCSTARTGETSVCSTART ABSVCSTARTSERVESTART ABSVCSTARTPUTRETURN ABRETURNGETRETURN ABRETURN

SERVERETURN ABRETURN

The routines return the relevant return codes associated with the XATMI-conformantroutines on which they are based. You do not need to know about the XATMI-conformant routines to use the high-level routines.


86 A2 63CD Rev01 A-11

A.3.1 Routine Usage

Each API routine has a SYNOPSIS of the form:

01 DELIVERY-POINT PIC X(15).01 MESSAGE-TYPE PIC X(16).01 DATA-REC. COPY USER-DATA.01 LEN PIC S9(9) COMP-2.01 MAX-LEN PIC S9(9) COMP-2.01 ABSTATUS-REC. COPY TPSTATUS. COPY ABSTATUS. COPY ABTRANS.*LINKAGE SECTION.01 TRANSACTION-STORAGE. COPY MY-TX-STORAGE. 02 FLOWBUS-TRANS. COPY FLOWBUS-TRANS-STORAGE.

SET FLOWBUS-TRANS-STORAGE IN ABSTATUS-REC TO ADDRESS OFFLOWBUS-TRANS.

CALL "CALL" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LENMAX-LEN ABSTATUS-REC.

When an application uses an API routine the following must be true:

• The application is configured to have a delivery point of the name specified in theparameter DELIVERY-POINT

• The API routine is correct for the delivery point type

For example, PUT is only used on client PUT delivery points

• There must be a connection at the delivery point configured to carry the messagebase type specified in the parameter MESSAGE-TYPE


A-12 86 A2 63CD Rev01

A.3.2 The DATA-BUFFER parameter

Each API routine assumes that a DATA-BUFFER parameter is supplied. TheDATA-BUFFER parameter must be a 01 level data item which is large enough to containthe longer of the sent and the received messages. Received messages include errormessages.

You can redefine DATA-BUFFER by the COPY files that define the format of themessages. For example, assume that:

• A CALL delivery point in the application profile is configured to send message basetype A

• The same CALL delivery point is configured to receive message base types B and C

You can include the following lines in the application:

01 DATA-BUFFER PIC X(nnnn).01 MESSAGE-TYPE-A REDEFINES DATA-BUFFER. COPY A.01 MESSAGE-TYPE-B REDEFINES DATA-BUFFER. COPY B.01 MESSAGE-TYPE-C REDEFINES DATA-BUFFER. COPY C.01 ERROR-MESSAGE-TYPE REDEFINES DATA-BUFFER 05 ERROR-MESSAGE PIC X(nnnn).

You can then code the CALL delivery point to send MESSAGE-TYPE-A and to receiveMESSAGE-TYPE-B and MESSAGE-TYPE-C. This ensures that DATA-BUFFER is largeenough.

See the section Message Base Types of this appendix for more about message basetypes.

A.3.3 Returned Messages

• When a service returns with an error, the client application receives a [TPESVCFAIL ]error.

When this happens, the following are set:

• MESSAGE-TYPE contains SPACES

• DATA-BUFFER contains the error message returned by the server application. If thereis no error message it contains SPACES.

• APPL-RETURN-CODE in TPSTATUS structure may contain an application-definedvalue that was returned by the service


86 A2 63CD Rev01 A-13

The following values are returned in APPL-RETURN-CODE if a request from a clientGET or a message from a client PUT is routed to a queue:

[QMEINVAL ] An invalid setting was specified

[QMEBADRMID ] An invalid resource manager identifier was specified

[QMENOTOPEN] The resource manager is not currently open

[QMETRAN] The call was made with TPNOTRAN set and an erroroccurred trying to start a transaction in which to dequeue themessage

[QMEBADMSGID ] An invalid message identifier was specified for dequeuing

[QMESYSTEM] A system error has occurred. The exact nature of the error iswritten to a log file.

[QMEOS] An operating system error has occurred

[QMENOTA] The transaction in which the message was dequeued wasaborted

[QMEPROTO] A dequeue was done when the transaction state was notactive

[QMEBADQUEUE ] An invalid or deleted queue name was specified

• When [TPOK] is returned to the client application, APPL-RETURN-CODE may alsocontain an application-defined value. If a request from a client GET or a messagefrom a client PUT is routed to a queue, the following values are returned:

[QMENOMSG] The queue is empty so no message was available fordequeuing

[QMEINUSE] There is an uncommitted message on the queue

In this case the length of the returned message is 0.

When a queue is empty, [TPOK] is returned and APPL-RETURN-CODE of TPSTATUSis set to QMENOMSG. An application which executes a GET, ABCALL, ABGETREPLYon a Delivery Point connected to a queue must test the APPL-RETURN-CODE to checkif the queue is empty.

If, as a result of a switch of network model, the delivery point is no longer connected to aqueue, this checking can be done.

When [QMEINUSE] is returned in APPL-RETURN-CODE, another application processhas read the message from the queue and may put the message back on the queue if itrolls back the transaction. Therefore, the application receiving [QMEINUSE] should retryreading the queue.

SERVE transformation instances always return 0 in APPL-RETURN-CODE.

PUT transformation instances return 0 in APPL-RETURN-CODE if each message sentfrom it succeeds. Otherwise, they return the value received from one of the failedmessages.


A-14 86 A2 63CD Rev01

GET transformation instances return 0 in APPL-RETURN-CODE if the message itrequests is returned successfully. Otherwise, they return the value received from therequested service.

You should not assume that APPL-RETURN-CODE will only contain particular errormessages. The application can be connected to a different application on FlowBus at anytime. For example, messages from a client PUT delivery point could initially be routeddirectly to a server application. If the same connection were later routed via a queue, theapplication could receive unexpected queue error messages. Unknown message valuesin APPL-RETURN-CODE should be processed in one or more of the following ways:

• Written to a log for diagnostic purposes

• Passed to the operator

• Displayed to the user

You may also wish to write a utility application to identify unknown message values.

A.4 HOW TO COMPILE YOUR FLOWBUS TPRS

The installation of FlowBus supplies the following files for building your FlowBusapplication TPRs:

• <dir>.flowbus.culib

compile unit library containing the FlowBus API functions bound in memberH_BUSAPI7.

• <dir>.flowbus.copy

source Library containing the FlowBus COBOL copy members.

Where <dir> is the top level directory name specified at the installation of FlowBus.

In order to compile your TPRs to use FlowBus you must add:

• the <dir>.flowbus.copy to the search path of your compilation JCL.

• the <dir>.flowbus.culib to the search path of your LINKER JCL.

Example JCL is given below:

lib sl inlib1=( <dir>.flowbus.copy ), inlib2=your.sllib;cobol source=your_tpr culib=(your.culib), xref ...;lib cu inlib1=( <dir>.flowbus.culib ), inlib2=your.culib;linker your_tpr,sm,outlib=(your.smlib), comfile=(your.sllibmb=tp7linktpr);


86 A2 63CD Rev01 A-15

NOTES: 1. that the FlowBus compile units supplied cannot be declared as'USE PROCEDURES' in the TDS generation member STDS.

2. that all Transactions using the FlowBus API must be declared withthe 'XCP2 SERVICE' statement in the Transaction section of theSTDS.

3. If the Local Queuing functionality is used, the following must beadded in tp7linktpr member:

REPLACE = (ABINIT, LQ-ABINIT),

REPLACE = (ABTERM, LQ-ABTERM),

REPLACE = (GET, LQ-GET),

REPLACE = (PUT, LQ-PUT)

(See Local Queuning User's Guide documentation).

A.4.1 Configuring the Application Loader

The Transaction BABEPA is the application loader service that runs on GCOS 7. In orderto be able to use this service the following steps must be carried out:

Update your STDS member to contain:

A declaration of the BABEPA Transaction, as follows:

MESSAGE "BABEPA" ASSIGN TO BABEPAIMPLICIT COMMITMENTXCP2 SERVICEAUTHORITY CODES ARE .....

Link the supplied compile unit BABEPA (delivered in library <dir>.flowbus.culib) into yourTDS shareable module Libraries. Example JCL is given below:

lib cu,inlib1( <dir>.flowbus.culib );linker BABEPA,sm,outlib=(your.smlib),comfile=(your.sllibmb=tp7linktpr);

Example JCL called 'LINK_TPR' is supplied in the library <dir>.flowbus.sample.sllib,which is the library containing the source of the example application Sampleapp.


A-16 86 A2 63CD Rev01

A.5 ROUTINE REFERENCES

A.5.1 ABACALL

NAME

*ABACALL - sends a message to a service asynchronously

SYNOPSIS

01 ABSVCDEF-REC.COPY TPSVCDEF.

01 ABTYPE-REC.COPY TPTYPE.

01 DATA-REC.COPY USER-DATA.

01 ABSTATUS-REC.COPY TPSTATUS.COPY ABSTATUS.COPY ABTRANS.

CALL "ABACALL" USING ABSVCDEF-REC ABTYPE-REC DATA-RECABSTATUS-REC.

DESCRIPTION

ABACALL allows a user program to send a request or query message asynchronouslyfrom a client delivery point. The ABACALL routine must be followed by a correspondingABGETRPLY routine.

The ABACALL routine and its corresponding ABGETRPLY routine must be codedappropriately for the delivery point specified in the parameter SERVICE-NAME inABSVCDEF-REC. For example, at a client GET delivery point the ABACALL routinespecifies only the message base type to be returned by the ABGETRPLY routine.


86 A2 63CD Rev01 A-17

The following table shows the required user settings for each routine at each type ofdelivery point:

DeliveryPoint

Parameter ABACALL ABGETRPLY

Client PUT DATA-REC User dataLEN in ABTYPE-REC Length of the outgoing

message0

SUB-TYPE inABTYPE-REC

Base type of theoutgoing message

Client GET DATA-RECLEN in ABTYPE-REC 0 Maximum length of

the requestedmessage


Base type of therequested message


CALL DATA-REC User dataLEN in ABTYPE-REC Length of the outgoing

messageMaximum length ofthe reply message



Base type of the replymessage

See the individual parameters for details of the values in each parameter on return fromthe routine.

The user program specifies the following parameters:

SERVICE-NAME in ABSVCDEF-REC

The name of the delivery point at which the application passes the message to FlowBus.This must be the name of a client PUT, client GET or CALL delivery point specified inthe application profile for this application.

DATA-REC

The message to be sent at a PUT or CALL delivery point.

This parameter is ignored at a GET delivery point.

REC-TYPE in ABTYPE-REC

This parameter must be "BAB".

SUB-TYPE in ABTYPE-REC

The base type of the message being sent at a PUT or CALL delivery point.

The base type of the message being requested at a GET delivery point.

In both cases, this must be the name of one of the message base types that the deliverypoint is configured to send or receive, as appropriate.


A-18 86 A2 63CD Rev01

LEN in ABTYPE-REC

The number of bytes of the data in DATA-REC that should be sent at a PUT or CALLdelivery point. If you wish to send the actual length of the message, you must determineit and move the value to this field.

This parameter must be 0 at a GET delivery point.

The maximum value for LEN in ABTYPE-REC is 32000.

FLAGS

The following is a list of valid settings in the ABSVCDEF-REC parameter.

TPNOTRAN

If the caller is in transaction mode and this setting is used, then when the service towhich this request is routed is invoked, it is not performed on behalf of the caller'stransaction. If the service to which this request is routed belongs to a server that does notsupport transactions, then this setting must be used when the caller is in transactionmode.

A caller in transaction mode that uses this setting is still subject to the transactiontimeout (and no other).

If a service fails that was invoked with this setting, the caller's transaction is not affected.

Either TPNOTRAN or TPTRAN must be set.

TPTRAN

If the caller is in transaction mode and this setting is used, then when the service towhich this request is routed is invoked, it is performed on behalf of the caller'stransaction.

This setting is ignored if the caller is not in transaction mode.


TPNOREPLY

TPNOREPLY informs ABACALL that a reply is not expected. When TPNOREPLY isset, the routine returns [TPOK] on success and sets COMM-HANDLE in ABSVCDEF-REC to 0, an invalid communications handle. When the caller is in transaction mode, thissetting cannot be used when TPTRAN is also set.

Either TPNOREPLY or TPREPLY must be set.

TPREPLY

TPREPLY informs ABACALL that a reply is expected. When TPREPLY is set, theroutine returns [TPOK] on success and sets COMM-HANDLE in ABSVCDEF-REC to avalid communications handle. When the caller is in transaction mode, this setting mustbe used when TPTRAN is also set.

Either TPNOREPLY or TPREPLY must be set.


86 A2 63CD Rev01 A-19

TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffersinto which the message is transferred are full).

Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

When TPBLOCK is specified and a blocking condition exists, the caller blocks until thecondition subsides or a timeout occurs (either transaction or blocking timeout).


TPNOTIME

This setting signifies that the caller is willing to block indefinitely and wants to be immuneto blocking timeouts.

Transaction timeouts may still occur.

Either TPNOTIME or TPTIME must be set.

TPTIME

This setting signifies that the caller will receive blocking timeouts if a blocking conditionexists and the blocking time is reached.


TPNOSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is notrestarted and the call fails.

Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is re-issued.


RETURN VALUES

On successful completion, ABACALL sets TP-STATUS in ABSTATUS-REC to [TPOK].In addition, it returns a valid communications handle in COMM-HANDLE in ABSVCDEF-REC. This must be used in the ABGETRPLY routine to receive the reply of the requestsent.


A-20 86 A2 63CD Rev01

ERRORS

Under the following conditions, ABACALL fails and sets TP-STATUS in ABSTATUS-REC to one of the following values. Unless otherwise noted, failure does not affect thecaller's transaction, if one exists.

[TPEINVAL ] Invalid arguments were given.

[TPENOENT] The service to which this request is routed does not exist oris not a query/response service.

[TPEITYPE] The sub-type specified is not one of the message base typesthat the delivery point is configured to send. Alternatively,REC-TYPE in ABTYPE-REC is not "BAB".

[TPELIMIT] The caller's request was not sent because the maximumnumber of outstanding asynchronous requests has beenreached.

[TPETRAN] The request is routed to a server that does not supporttransactions.

[TPETIME] A time-out occurred. If the caller is in transaction mode, thena transaction time-out occurred and the transaction ismarked abort-only. If a transaction time-out occurred, thenany attempts to send new requests or receive outstandingreplies will fail with this error message until the transactionhas been aborted.

[TPEBLOCK ] A blocking condition exists and TPNOBLOCK was specified.

[TPEGOTSIG] A signal was received and TPNOSIGRSTRT was specified.

[TPEPROTO] ABACALL was called in an improper context.

[TPESYSTEM] A FlowBus error has occurred. The exact nature of the erroris written to a log file.

[TPEOS] An operating system error has occurred.

SEE ALSO

ABCALL , ABGETRPLY

Example:

01 ABSVCDEF-REC. COPY TPSVCDEF.

01 ABTYPE-REC. COPY TPTYPE.

01 DATA-REC. COPY USER-DATA.


86 A2 63CD Rev01 A-21

01 ABSTATUS-REC. COPY TPSTATUS. COPY ABSTATUS. COPY ABTRANS.

01 WS-HANDLE PIC S9(9) COMP-2.

LINKAGE SECTION. COPY TDS-STORAGE. COPY CONSTANT-STORAGE.01 TRANSACTION-STORAGE. 02 FLOWBUS-TRANS. COPY FLOWBUS-TRANS-STORAGE.

PROCEDURE DIVISION USING TDS-STORAGE CONSTANT-STORAGE TRANSACTION-STORAGE.

INITIALIZE ABSVCDEF-REC. MOVE "User Data" TO DATA-REC. MOVE "CALL_DP_NAME" TO SERVICE-NAME.

SET TPTRAN TO TRUE. SET TPREPLY TO TRUE. SET TPBLOCK TO TRUE. SET TPTIME TO TRUE. SET TPNOSIGRSTRT TO TRUE.

MOVE "BAB" TO REC-TYPE IN ABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN ABTYPE-REC. MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC.

SET FLOWBUS-TRANS-STORAGE IN ABSTATUS-REC TO ADDRESS OF FLOWBUS-TRANS.

CALL "ABACALL" USING ABSVCDEF-REC ABTYPE-REC DATA-REC ABSTATUS-REC. IF NOT TPOK DISPLAY "ABACALL failed. The error returned was " TP-STATUS ELSE MOVE COMM-HANDLE TO WS-HANDLE.

MOVE WS-HANDLE TO COMM-HANDLE. MOVE "BAB" TO REC-TYPE IN ABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN ABTYPE-REC. MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC.

CALL "ABGETRPLY" USING ABSVCDEF-REC ABTYPE-REC DATA-REC ABSTATUS-REC.

IF QMENOMSG OR QMEINUSE DISPLAY "Queue is empty" ELSE IF NOT TPOK DISPLAY "ABGETRPLY failed. The error returned was " TP-STATUS.

SUGGESTED READING

Prerequisite Information

Glossary Terms: PUT; GET; CALL/SERVE; delivery point; asynchronous call

Related Information

TUXEDO Reference Manual


A-22 86 A2 63CD Rev01

A.5.2 ABCALL

NAME

*ABCALL - invokes a service.

SYNOPSIS


01 IABTYPE-REC.COPY TPTYPE.

01 IDATA-REC.COPY USER-DATA.

01 OABTYPE-REC.COPY TPTYPE.

01 ODATA-REC.COPY USER-DATA.


CALL "ABCALL" USING ABSVCDEF-REC IABTYPE-REC IDATA-RECOABTYPE-REC ODATA-REC ABSTATUS-REC.

DESCRIPTION

ABCALL allows a user program to call a service. The call consists of a query messageand a reply message. They must be handled by an ABSVCSTART routine and anABRETURN routine in the called service. (These routines are used by the high-levelserver routines, which can therefore also handle query/response messages.) Withappropriate parameters, the ABCALL routine can be used to send a notification messageor to receive a notification message. All processes are synchronous.

The ABCALL routine is the equivalent of an ABACALL routine followed by anABGETRPLY routine.

The ABCALL routine must be coded appropriately for the delivery point specified in theparameter SERVICE-NAME in ABSVCDEF-REC. For example, at a client GET deliverypoint the ABCALL routine specifies only the message base type to be returned by theABRETURN routine.


86 A2 63CD Rev01 A-23

The following table shows the required user settings for the ABCALL routine at each typeof delivery point:

DeliveryPoint

Parameter Value

Client PUT IDATA-REC User dataODATA-RECLEN In IABTYPE-REC Length of the outgoing messageLEN In OABTYPE-REC Maximum length of the error message

expectedSUB-TYPE In IABTYPE-REC Base type of the message in IDATA-RECSUB-TYPE in OABTYPE-REC

Client GET IDATA-RECODATA-RECLEN In IABTYPE-REC 0LEN In OABTYPE-REC Maximum length of the requested

messageSUB-TYPE In IABTYPE-REC Base type of the message to be returned

by the serverSUB-TYPE in OABTYPE-REC

CALL IDATA-REC User dataODATA-RECLEN In IABTYPE-REC Length of the outgoing messageLEN In OABTYPE-REC Maximum length of the requested

messageSUB-TYPE In IABTYPE-REC Base type of the message in IDATA-RECSUB-TYPE in OABTYPE-REC



SERVICE-NAME in ABSVCDEF-REC

The name of the delivery point at which the application passes the message to FlowBus.This must be the name of a client PUT, client GET or CALL delivery point specified inthe application profile for this application.

IDATA-REC

The message to be sent at a PUT or CALL delivery point. This parameter is ignored at aGET delivery point.

REC-TYPE in IABTYPE-REC


REC-TYPE in OABTYPE-REC



A-24 86 A2 63CD Rev01

SUB-TYPE in IABTYPE-REC

The base type of the message being sent at a PUT or CALL delivery point. This must bethe name of one of the message base types that the delivery point is configured to send.

The base type of the message being requested at a GET delivery point. This must bethe name of one of the message base types that the delivery point is configured toreceive.

SUB-TYPE in OABTYPE-REC

On return, this parameter contains the actual base type of the message received.

LEN in IABTYPE-REC

The number of bytes of the data in IDATA-REC that should be sent at a PUT or CALLdelivery point. If you wish to send the actual length of the message, you must determineit and move the value to this field.

This parameter must be 0 at a GET delivery point.

The maximum value for LEN in IABTYPE-REC is 32000.

LEN in OABTYPE-REC

The number of bytes of the data in ODATA-REC that should be written to the application.

It is an error for this parameter to be 0 on input.

The maximum value for LEN in OABTYPE-REC is 32000.

On return, this parameter contains the actual number of bytes written.

If LEN in OABTYPE-REC is 0 upon successful return, then the reply has no data portionand ODATA-REC is not modified.

FLAGS

The following is a list of valid settings in ABSVCDEF-REC.

TPNOTRAN

If the caller is in transaction mode and this setting is used, then when the service towhich this request is routed is invoked, it is not performed on behalf of the caller'stransaction. If the service to which this request is routed belongs to a server that does notsupport transactions, then this setting must be used when the caller is in transactionmode.

A caller in transaction mode that uses this setting is still subject to the transactiontimeout (and no other).

If a service fails that was invoked with this setting, the caller's transaction is not affected.



86 A2 63CD Rev01 A-25

TPTRAN

If the caller is in transaction mode and this setting is used, then when the service towhich this request is routed is invoked, it is performed on behalf of the caller'stransaction.

This setting is ignored if the caller is not in transaction mode.


TPNOCHANGE

When this setting is used, the type of the message is not allowed to change. That is, thetype and sub-type of the reply must match the type of the message sent, so long as thereceiver recognizes the incoming record type.

Either TPNOCHANGE or TPCHANGE must be set.

TPCHANGE

The type and/or subtype of the reply record are allowed to differ from those of themessage sent, so long as the receiver recognizes the incoming record type.


TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffersinto which the message is transferred are full).


TPBLOCK



TPNOTIME




TPTIME




A-26 86 A2 63CD Rev01

TPNOSIGRSTRT



TPSIGRSTRT



RETURN VALUES

Upon successful completion, ABCALL sets TP-STATUS in ABSTATUS-REC to [TPOK].When TP-STATUS in ABSTATUS-REC is set to [TPOK], ODATA-REC contains themessage returned by the service, SUB-TYPE in OABTYPE-REC contains the name ofthe message type returned by the service and LEN in OABTYPE-REC contains thelength of the message. If the size of the incoming message is larger than the sizerequested on input in LEN in OABTYPE-REC, TPTRUNCATE is set and only therequested amount of data is moved to ODATA-REC. The remaining data is discarded.

ERRORS

Under the following conditions, ABCALL fails and sets TP-STATUS in ABSTATUS-RECto one of the following values. Unless otherwise noted, failure does not affect the caller'stransaction, if one exists.

[TPEINVAL ] Invalid arguments were given (for example, SERVICE-NAME is SPACES).


[TPEITYPE] The message base type sent is not one of the message basetypes that the delivery point is configured to send.Alternatively, REC-TYPE in IABTYPE-REC is not "BAB".

[TPEOTYPE] The message base type received is not one of the messagebase types that the delivery point is configured to receive.Alternatively, REC-TYPE in OABTYPE-REC is not "BAB". IfTPNOCHANGE is set, this error is also returned when thebase type of the incoming messsage does not match themessage base type of the outgoing message.


[TPETIME] A timeout occurred.


86 A2 63CD Rev01 A-27

[TPESVCFAIL ] The service routine sending the caller's reply calledABRETURN with TPFAIL . This is an application-levelfailure. The error message returned by the server, if one wassent, and its length are respectively available in ODATA-REC and in LEN in OABTYPE-REC. If there is truncation,TPTRUNCATE is set.

[TPESVCERR] An error was encountered either in invoking a service routineor during its completion in ABRETURN . For example, badarguments were passed. No reply data is returned when thiserror occurs.


[TPEGOTSIG] A signal was received and TPNOSIGRSTRT was specified.

[TPEPROTO] ABCALL was called in an improper context.



SEE ALSO

ABINIT , ABTERM , ABRETURN , ABACALL , ABGETRPLY , ABSVCSTART

Example:


01 IABTYPE-REC. COPY TPTYPE.

01 IDATA-REC. COPY USER-DATA.

01 OABTYPE-REC. COPY TPTYPE.

01 ODATA-REC. COPY USER-DATA.




A-28 86 A2 63CD Rev01


INITIALIZE ABSVCDEF-REC. MOVE "User Data" TO IDATA-REC. MOVE "CALL_DP_NAME" TO SERVICE-NAME IN ABSVCDEF-REC.

SET TPTRAN TO TRUE. SET TPNOCHANGE TO TRUE. SET TPBLOCK TO TRUE. SET TPTIME TO TRUE. SET TPNOSIGRSTRT TO TRUE.

MOVE "BAB" TO REC-TYPE IN IABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN IABTYPE-REC. MOVE LENGTH OF IDATA-REC TO LEN IN IABTYPE-REC. MOVE "BAB" TO REC-TYPE IN OABTYPE-REC. MOVE SPACES TO SUB-TYPE IN OABTYPE-REC. MOVE LENGTH OF ODATA-REC TO LEN IN OABTYPE-REC.


CALL "ABCALL" USING ABSVCDEF-REC IABTYPE-REC IDATA-REC OABTYPE-REC ODATA-REC ABSTATUS-REC.

IF QMENOMSG OR QMEINUSE DISPLAY "Queue is empty" ELSE IF NOT TPOK DISPLAY "ABCALL failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: PUT; GET; CALL/SERVE; delivery point; synchronous call

Related Information



86 A2 63CD Rev01 A-29

A.5.3 ABGETRPLY

NAME

*ABGETRPLY - gets a reply from an asynchronous message

SYNOPSIS





CALL "ABGETRPLY" USING ABSVCDEF-REC ABTYPE-REC DATA-RECABSTATUS-REC.

DESCRIPTION

ABGETRPLY allows a user program to receive a reply from a previously sent request orquery message asynchronously at a client delivery point. The ABGETRPLY routinemust be preceded by a corresponding ABACALL routine. It references the COMM-HANDLE value returned by this ABACALL routine. It receives a response sent by anABRETURN routine in the called service.

The ABGETRPLY routine and its corresponding ABACALL must be codedappropriately for the delivery point specified in the parameter SERVICE-NAME inABSVCDEF-REC . For example, at a client GET delivery point the ABGETRPLY routinespecifies only the message base type to be returned by the ABGETRPLY routine. Forexample, at a client PUT delivery point the ABGETRPLY routine specifies an emptyresponse message.


A-30 86 A2 63CD Rev01

The following table shows the required user settings for each routine at each type ofdelivery point:

DeliveryPoint

Parameter ABACALL ABGETRPLY

Client PUT DATA-REC User dataLEN in ABTYPE-REC Length of the outgoing

message0



Client GET DATA-RECLEN in ABTYPE-REC 0 Maximum length of

the requestedmessage




CALL DATA-REC User dataLEN in ABTYPE-REC Length of the outgoing

messageMaximum length ofthe reply message



Base type of the replymessage






The base type of the message requested or returned at a GET or CALL delivery point.

This parameter is ignored at a PUT delivery point.

LEN in ABTYPE-REC

The number of bytes of the data in DATA-REC that should be written to the application.

It is an error for this parameter to be 0 on input at a GET or CALL delivery point.


On return, this parameter contains the actual number of bytes written.

If LEN in ABTYPE-REC is 0 on successful return, then the reply has no data portion andDATA-REC is not modified.


86 A2 63CD Rev01 A-31

COMM-HANDLE in ABSVCDEF-REC

A valid communications handle returned by a previous ABACALL . This enablesABGETRPLY to receive the reply of the corresponding request.

FLAGS

The following flags must be set in ABSVCDEF-REC.

TPGETANY

This setting signifies that ABGETRPLY should ignore the communications handleindicated by COMM-HANDLE in ABSVCDEF-REC, return any reply available and setCOMM-HANDLE in ABSVCDEF-REC to the communications handle for the replyreturned. If no replies exist, ABGETRPLY can wait for one to arrive.

Either TPGETANY or TPGETHANDLE must be set.

TPGETHANDLE

This setting signifies that ABGETRPLY should use the communications handle identifiedby COMM-HANDLE in ABSVCDEF-REC and return a reply available for thatcommunications handle. If no replies exist, ABGETRPLY can wait for one to arrive.

Either TPGETANY or TPGETHANDLE must be set.

TPNOCHANGE

When this setting is used, the type of the message is not allowed to change. That is, thetype and sub-type of the reply must match the type of the message sent by ABACALLso long as the receiver recognizes the incoming record type.


TPCHANGE

The type and/or subtype of the reply record are allowed to differ from those of themessage sent by ABACALL so long as the receiver recognizes the incoming recordtype.


TPNOBLOCK

ABGETRPLY returns without waiting for the reply to arrive. However, if the reply isalready available, ABGETRPLY gets the reply and returns.


TPBLOCK




A-32 86 A2 63CD Rev01

TPNOTIME




TPTIME



TPNOSIGRSTRT



TPSIGRSTRT



RETURN VALUES

Upon successful completion, ABGETRPLY sets TP-STATUS in ABSTATUS-REC to[TPOK]. When TP-STATUS in ABSTATUS-REC is set to [TPOK], DATA-REC containsthe message received, SUB-TYPE in ABTYPE-REC contains the name of the messagetype returned and LEN in ABTYPE-REC contains the length of the message. If the sizeof the incoming message is larger than the size requested on input in LEN in ABTYPE-REC, TPTRUNCATE is set and only the requested amount of data is moved to DATA-REC. The remaining data is discarded.


86 A2 63CD Rev01 A-33

ERRORS

Under the following conditions, ABGETRPLY fails and sets TP-STATUS in ABSTATUS-REC to one of the following values. Note that if TPGETHANDLE is set, then COMM-HANDLE in ABSVCDEF-REC is invalid unless otherwise stated. If TPGETANY is set,then the communications handle is the one for the reply on which the failure occurred; ifan error occurred before a reply could be retrieved, then the value of thecommunications handle is 0. Also, the failure does not affect the caller's transaction, ifone exists, unless otherwise stated. DATA-REC and SUB-TYPE in ABTYPE-REC doesnot change unless otherwise specified.

[TPEINVAL ] Invalid arguments were given (for example, settings inABSVCDEF-REC are invalid).

[TPEOTYPE] The message base type received is not one of the messagebase types that the delivery point is configured to receive.Alternatively, REC-TYPE in ABTYPE-REC is not "BAB". IfTPNOCHANGE is set, this error is also returned when thebase type of the incoming message does not match themessage base type of the outgoing message sent byABGETRPLY .

[TPEBADDESC ] The communications handle is invalid.

[TPETIME] A timeout occurred. If the caller is in transaction mode, thena transaction timeout occurred and the transaction is markedabort-only. If TPGETHANDLE was set, the communicationshandle remains valid unless the caller is in transaction mode.If a transaction timeout occurred, then any attempts to sendnew requests or receive outstanding replies will fail with[TPETIME] until the transaction has been aborted.

[TPESVCFAIL ] The service routine sending the caller's reply calledABRETURN with TPFAIL . This is an application-levelfailure. The contents of the service's reply, if one was sent,and its length are available instead of the requestedmessage. An application defined value was also sent as partof ABRETURN. If the reply was received on behalf of thecaller's transaction, then the transaction is marked abort-only. Note that so long as the transaction has not timed out,further communication may be performed before abortingthe transaction. Any work performed on behalf of the caller'stransaction will be aborted when the transaction iscompleted. For subsequent communication to have anylasting effect, it should be done with TPNOTRAN set.


A-34 86 A2 63CD Rev01

[TPESVCERR] An error was encountered by a service routine during itscompletion in ABRETURN (for example, bad argumentswere passed). No reply data is returned when this erroroccurs. If the reply was received on behalf of the caller'stransaction, then the transaction is marked abort-only. Notethat so long as the transaction has not timed out, furthercommunication may be performed before aborting thetransaction and that any work performed on behalf of thecaller's transaction will be aborted upon transactioncompletion. This means that, subsequent communicationshould be done with TPNOTRAN set if it is to have anylasting effect.


[TPGOTSIG] A signal was received and TPNOSIGRSTRT was specified.

[TPEPROTO] ABGETRPLY was called in an improper context. That is, itwas called without a corresponding ABACALL or outside atransaction.



SEE ALSO

ABACALL , ABRETURN

Example:





01 WS-HANDLE PIC S9(9) COMP-2.



86 A2 63CD Rev01 A-35


INITIALIZE ABSVCDEF-REC. MOVE "User Data" TO DATA-REC. MOVE "CALL_DP_NAME" TO SERVICE-NAME.

SET TPTRAN TO TRUE. SET TPREPLY TO TRUE. SET TPBLOCK TO TRUE. SET TPTIME TO TRUE. SET TPNOSIGRSTRT TO TRUE.

MOVE "BAB" TO REC-TYPE IN ABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN ABTYPE-REC. MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC.


CALL "ABACALL" USING ABSVCDEF-REC ABTYPE-REC DATA-REC ABSTATUS-REC. IF NOT TPOK DISPLAY "ABACALL failed. The error returned was " TP-STATUS ELSE MOVE COMM-HANDLE TO WS-HANDLE.

MOVE WS-HANDLE TO COMM-HANDLE. MOVE "BAB" TO REC-TYPE IN ABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN ABTYPE-REC. MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC.

CALL "ABGETRPLY" USING ABSVCDEF-REC ABTYPE-REC DATA-REC ABSTATUS-REC.

IF QMENOMSG OR QMEINUSE DISPLAY "Queue is empty" ELSE IF NOT TPOK DISPLAY "ABGETRPLY failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: PUT; GET; CALL/SERVE; delivery point

Related Information



A-36 86 A2 63CD Rev01

A.5.4 ABINIT

NAME

*ABINIT - initializes the interface with FlowBus. This routine is optional, except forapplication instances that use Local Queuing on Export machines.

SYNOPSIS

01 ABINFDEF-REC.COPY ABINFDEF.

COPY ABSECURITY.


CALL "ABINIT" USING ABINFDEF-REC ABSTATUS-REC.

DESCRIPTION

ABINIT allows an application thread to bind with FlowBus. Before an application can useany of the low-level FlowBus API routines, it should first call ABINIT . After ABINITsuccessfully returns, the application can initiate service requests over FlowBus.

ABINIT can not be called more than once (that is, after the client has already joinedFlowBus).

If ABINIT is not called, the first ABCALL , ABACALL (or PUT, GET or CALL) orABSVCSTART (or GETSVCSTART, PUTSVCSTART or SERVESTART) will perform anABINIT using the value of the environment variable BAB_APP_INST_ID (in generalenvironment for BABC7 client agent, or in specific environment for each BABS7 serveragent).

If Local Queuing is not used on the GCOS 7 System, IDS/II is not used by FlowBus andABINIT is not mandatory. If Local Queuing is used somewhere on the system, IDS/II isused and ABINIT is mandatory for all the FlowBus client applications, using LocalQueuing or not.

In the Local Queuing context: the application instance specified in APP-INST-ID inABINFDEF-REC may be a synchronous, asynchronous or mixed one, depending onwhich kind of connections it uses.


86 A2 63CD Rev01 A-37

ABINIT accesses the IDS/II database in order to determinate the type of the currentinstance:

If all the connections of this instance use Local Queuing, the application instance is anASYNCHRONOUS one. PUT and GET will deposit the messages in the IDS/IIdatabase. These messages will be transferred afterwards to the FlowBus kernel by a“ transfer ” command. This application instance is registered in the IDS/II database. Inthis case, the XCP2 communication pool need not to be started until the transfer isstarted.

If Local Queuing is not used for this application instance, it is a SYNCHRONOUS one:PUT and GET synchronously route the messages to/from the FlowBus kernel. Thisapplication instance is not registered in the IDS/II database. In this case, the XCP2communication pool must be started.

If this application instance uses both synchronous and asynchronous connections, it isa MIXED one: the PUTs and GETs will be asynchronous while CALL will besynchronous. This application instance is registered in the IDS/II database. In thiscase, the pool must be started.


APP-INST-ID in ABINFDEF-REC

The name of the application instance in the FlowBus configuration that corresponds tothe current application.

RETURN VALUES

Upon successful completion, ABINIT sets TP-STATUS in ABSTATUS-REC to [TPOK].

ERRORS

Under the following conditions, ABINIT fails and sets TP-STATUS in ABSTATUS-REC toone of the following values. Unless otherwise noted, failure does not affect the caller'stransaction, if one exists.


[TPENOENT] The application cannot initialize FlowBus because of spacelimitations.

[TPEPROTO] ABINIT was called in an improper context, for example in aservice.For a synchronous or mixed instance, this return code maybe set if the XCP2 communication pool is not ready.




A-38 86 A2 63CD Rev01

[TPERMERR] For ASYNCHRONOUS/MIXED application only. An erroroccured in the IDS/II database management.This results to an abort of the transaction. The exact natureof the IDS/II error is written in the JOR of the TDS.

SEE ALSO

ABCALL , ABACALL , ABSVCSTART , ABTERM

Example:

01 ABINFDEF-REC. COPY ABINFDEF. COPY ABSECURITY.





MOVE "BUSCOR" TO BAB-XCP2-COR. MOVE "BUSPOOL" TO BAB-XCP2-POOL. MOVE "INSTANCE-ID" TO APP-INST-ID IN ABINFDEF-REC. MOVE SPACES TO SYMB-DEST-NAME IN ABINFDEF-REC.

CALL "ABINIT" USING ABINFDEF-REC ABSTATUS-REC.

IF NOT TPOK DISPLAY "ABINIT failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: transaction

Related Information



86 A2 63CD Rev01 A-39

A.5.5 ABRETURN

NAME

*ABRETURN - returns from a FlowBus service routine

SYNOPSIS

01 ABSVCRET-REC.COPY TPSVCRET.




CALL "ABRETURN" USING ABSVCRET-REC ABTYPE-REC DATA-RECABSTATUS-REC.

DESCRIPTION

ABRETURN lets a user program return a response from a server delivery point. TheABRETURN routine must be preceded by a corresponding ABSVCSTART routine.

Since the ABRETURN routine contains an EXIT PROGRAM statement, it should not beinvoked in a sub-program of the service routine. If it is so used, control does not return tothe FlowBus dispatcher.

The ABRETURN routine sends a response message to a query sent by an ABCALLroutine in a client application or a request sent by an ABGETRPLY routine in a clientapplication. After a successful ABRETURN routine, the response message is available inthe client application's record.

If a service routine was in transaction mode, ABRETURN places the service's portion ofthe transaction in a state where it may be either committed or aborted when thetransaction is completed. A service may be invoked more than once as part of the sametransaction. It is not necessarily fully committed or aborted until either TXCOMMIT orTXROLLBACK is called by the originator of the transaction.

ABRETURN should be called after receiving all replies expected from request/responseservice requests initiated by the service routine. Any outstanding replies which are notreceived will automatically be dropped by the FlowBus dispatcher upon receipt. Inaddition, the communications handle for those replies become invalid.


A-40 86 A2 63CD Rev01

At a server GET delivery point the ABRETURN routine specifies an empty outgoingmessage.

The following table shows the required user settings for the ABRETURN routine at eachtype of delivery point:

DeliveryPoint

Parameter Value

Server PUT DATA-REC User dataLEN in ABTYPE-REC Length of the outgoing messageSUB-TYPE in ABTYPE-REC Base type of the message in DATA-REC

Server GET DATA-REC Error message if requiredLEN in ABTYPE-REC 0 or length of the error messageSUB-TYPE in ABTYPE-REC SPACES

SERVE DATA-REC User dataLEN in ABTYPE-REC Length of the outgoing messageSUB-TYPE in ABTYPE-REC Base type of the message in DATA-REC



DATA-REC

The message to be sent at a PUT or SERVE delivery point.

This parameter may contain an error message at a GET delivery point.



LEN in ABTYPE-REC

The number of bytes of the data in DATA-REC that should be sent at a PUT or SERVEdelivery point. If you wish to sent the actual length of the message, you must determine itand move the value to this field.

This parameter will be either 0 or the length of an error message at a GET delivery point.

The maximum value allowed for LEN in ABTYPE-REC is 32000.


The base type of the message being sent at a PUT or SERVE delivery point. This mustbe the name of one of the message base types that the delivery point is configured tosend or receive, as appropriate.

This parameter must be SPACES at a GET delivery point.


86 A2 63CD Rev01 A-41

TP-RETURN-VAL in ABSVCRET-REC

This parameter can be set to one of the following.

TPSUCCESS The service has terminated successfully. If data is present,then it will be sent (barring any failures processing thereturn). If the caller is in transaction mode, then ABRETURNplaces the caller's portion of the transaction in a state suchthat it can be committed when the transaction ultimatelycommits. Note that a call to ABRETURN does notnecessarily end a transaction. Also, even though the callerindicates success, if there are any outstanding replies, if anywork done within the service caused its transaction to bemarked abort-only, then a failed message is sent. In thiscase the recipient of the reply receives a TPESVCERRindication. Note that if a transaction becomes abort-onlywhile in the service routine for any reason, then TP-RETURN-VAL should be set to TPFAIL .

TPFAIL The service has terminated unsuccessfully from anapplication standpoint. An error will be reported to theprogram receiving the reply. That is, the call to get the replywill fail and the recipient receives a [TPESVCFAIL ]indication. If the caller is in transaction mode, thenABRETURN marks the transaction as abort-only (note thatthe transaction may already be marked abort-only). Barringany failures in processing the return, the caller's data is sent,if present. One reason for not sending the caller's data iswhen a transaction timeout has occurred. In this case, theprogram waiting for the reply will receive an error of[TPETIME].

NOTE: that SUB-TYPE in ABTYPE-REC must be SPACES when TP-RETURN-VAL isset to TPFAIL .

TPEXIT This value is the same as TPFAIL , with respect tocompleting the service, but the server will exit after thetransaction is marked as abort-only and the reply is sentback to the requester. If the server is restartable, then theserver will automatically be restarted.

If TP-RETURN-VAL is not set to one of these three values, then it defaults to TPFAIL .

APPL-CODE in ABSVCRET-REC

This parameter specifies an application-defined return code that may be sent to thereceiving application. This code is sent regardless of the setting of TP-RETURN-VALprovided a reply can be successfully sent. A reply can be sent if the service returns[TPSUCCESS] or [TPFAIL ]. The value of APPL-CODE is available to the receivingapplication in APPL-RETURN-CODE in ABSTATUS-REC.


A-42 86 A2 63CD Rev01

RETURN VALUES

Since ABRETURN contains an EXIT PROGRAM statement, no value is returned to thecaller. Control does not return to the service routine. If a service routine returns withoutusing ABRETURN , the behaviour of the system is undefined. This occurs if theapplication uses an EXIT PROGRAM statement directly or just simply "falls out of theservice routine''.

ERRORS

Since ABRETURN ends the service routine, any errors encountered either in handlingarguments or in processing cannot be indicated to the routine's caller. Such errors causeTP-STATUS in ABSTATUS-REC to be set to [TPESVCERR] for a program receiving theservice's outcome via either ABCALL or ABGETRPLY .

SEE ALSO

ABSVCSTART , ABCALL , ABGETRPLY

Example:

PROGRAM-ID. SERVICENAME.


01 ABSVCRET-REC. COPY TPSVCRET.






MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC.


CALL "ABSVCSTART" USING ABSVCDEF-REC ABTYPE-REC DATA-REC ABSTATUS-REC.

IF NOT TPOK DISPLAY "ABSVCSTART failed. The error returned was " TP-STATUS


86 A2 63CD Rev01 A-43

SET TPFAIL TO TRUE MOVE ZERO TO APPL-CODE IN ABSVCRET-REC MOVE "BAB" TO REC-TYPE IN ABTYPE-REC MOVE ZERO TO LEN IN ABTYPE-REC MOVE SPACES TO SUB-TYPE IN ABTYPE-REC

CALL "ABRETURN" USING ABSVCRET-REC ABTYPE-REC DATA-REC ABSTATUS-REC

EXIT PROGRAM.

SET TPSUCCESS TO TRUE. MOVE ZERO TO APPL-CODE IN ABSVCRET-REC. MOVE "BAB" TO REC-TYPE IN ABTYPE-REC MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN ABTYPE-REC. MOVE "User Data" TO DATA-REC.

CALL "ABRETURN" USING ABSVCRET-REC ABTYPE-REC DATA-REC ABSTATUS-REC.

EXIT PROGRAM.

SUGGESTED READING



Related Information



A-44 86 A2 63CD Rev01

A.5.6 ABSVCSTART

NAME

*ABSVCSTART - starts a FlowBus service

SYNOPSIS



01 DATA-REC.COPY USER-DATA


CALL "ABSVCSTART" USING ABSVCDEF-REC ABTYPE-REC DATA-RECABSTATUS-REC.

DESCRIPTION

ABSVCSTART is the first FlowBus routine to be called when writing a service routine. Infact, it is an error to issue any other call within a service routine before callingABSVCSTART . ABSVCSTART is used to retrieve the service's parameters and data.This routine is used for services that receive requests via ABCALL or ABACALL .

Service routines processing requests made via either ABCALL or ABACALL receive atmost one incoming message (upon successfully returning from ABSVCSTART ) andsend at most one reply (upon exiting the service routine with ABRETURN).

Concerning transactions, service routines can participate in at most one transaction ifinvoked in transaction mode. As far as the service routine writer is concerned, thetransaction ends upon returning from the service routine. Note that ABRETURN is notused to complete a transaction. Thus, it is an error to call ABRETURN with anoutstanding transaction that originated within the service routine.


DATA-REC

The message to be obtained at a GET or CALL delivery point.

This parameter is ignored at a PUT delivery point.


86 A2 63CD Rev01 A-45

LEN in ABTYPE-REC

If LEN is 0 upon successful return, then the service has no incoming data and DATA-REC was not modified.

It is an error for LEN to be 0 on input.


RETURN VALUES

Upon successful completion, ABSVCSTART sets TP-STATUS in ABSTATUS-REC to[TPOK]. When TP-STATUS in ABSTATUS-REC is set to [TPOK], DATA-REC containsthe message returned by the service, SUB-TYPE in ABTYPE-REC contains the name ofthe message type returned by the service and LEN contains the length of the message. Ifthe size of the incoming message is larger then the size specified in LEN on input,TPTRUNCATE is set and only LEN amount of data is moved to DATA-REC. Theremaining data is discarded.

Also, SERVICE-NAME in ABSVCDEF-REC is populated with the delivery point namethat the message arrived on. The following values may be set in ABSVCDEF-REC :

TPTRAN The service routine is in transaction mode. This setting ismutually exclusive with TPNOTRAN.

TPREPLY The program invoking the service routine is expecting areply. This setting is meaningful only when TPREQRSP isset. This setting is mutually exclusive with TPNOREPLY.

ERRORS

Under the following conditions, ABSVCSTART fails and sets TP-STATUS inABSTATUS-REC to one of the following values:


[TPEPROTO] ABSVCSTART was called in an improper context.



SEE ALSO

ABCALL , ABACALL , ABRETURN , ABINIT .


A-46 86 A2 63CD Rev01

Example:

PROGRAM-ID. SERVICENAME.








MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC.


CALL "ABSVCSTART" USING ABSVCDEF-REC ABTYPE-REC DATA-REC ABSTATUS-REC. IF NOT TPOK DISPLAY "ABSVCSTART failed. The error returned was " TP-STATUS

SET TPFAIL TO TRUE MOVE ZERO TO APPL-CODE IN ABSVCRET-REC MOVE "BAB" TO REC-TYPE IN ABTYPE-REC MOVE ZERO TO LEN IN ABTYPE-REC MOVE SPACES TO SUB-TYPE IN ABTYPE-REC

CALL "ABRETURN" USING ABSVCRET-REC ABTYPE-REC DATA-REC ABSTATUS-REC

EXIT PROGRAM.

SET TPSUCCESS TO TRUE. MOVE ZERO TO APPL-CODE IN ABSVCRET-REC. MOVE "BAB" TO REC-TYPE IN ABTYPE-REC MOVE LENGTH OF DATA-REC TO LEN IN ABTYPE-REC. MOVE "MESSAGE-TYPE" TO SUB-TYPE IN ABTYPE-REC. MOVE "User Data" TO DATA-REC.

CALL "ABRETURN" USING ABSVCRET-REC ABTYPE-REC DATA-REC ABSTATUS-REC.

EXIT PROGRAM.


86 A2 63CD Rev01 A-47

SUGGESTED READING


Glossary Terms: PUT; GET; CALL/SERVE.

Related Information



A-48 86 A2 63CD Rev01

A.5.7 ABTERM

NAME

*ABTERM - closes the interface with FlowBus. This routine is optional, except forapplication instances that use Local Queuing on Export machines.

SYNOPSIS


CALL "ABTERM" USING ABSTATUS-REC.

DESCRIPTION

ABTERM signals to FlowBus that an application has ended its interaction with FlowBus.If the client is in transaction mode, then the call fails and the caller is still part of theapplication and in transaction mode. When ABTERM returns successfully, the caller canno longer communicate with other applications over FlowBus.

ABTERM can not be called more than once (that is, after the caller has already left theapplication).

RETURN VALUES

Upon successful completion, ABTERM sets TP-STATUS in ABSTATUS-REC to [TPOK].

ERRORS

Under the following conditions, ABTERM fails and sets TP-STATUS in ABSTATUS-RECto one of the following values:

[TPEPROTO] ABTERM was called in an improper context.



[TPERMERR] For ASYNCHRONOUS/MIXED application only. An erroroccured during the IDS/II datatabase access, and thetransaction is aborted. The exact nature of the IDS/II iswritten to the JOR of the TDS.


86 A2 63CD Rev01 A-49

SEE ALSO

ABINIT .

Example:



CALL "ABTERM" USING ABSTATUS-REC.

IF NOT TPOK DISPLAY "ABTERM failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: transaction

Related Information



A-50 86 A2 63CD Rev01

A.5.8 CALL

NAME

CALL - delivers a query message to FlowBus and waits for the response.

SYNOPSIS

01 DELIVERY-POINT PIC X(15).01 MESSAGE-TYPE PIC X(16).01 DATA-REC.

COPY USER-DATA.01 LEN PIC S9(9) COMP-2.01 MAX-LEN PIC S9(9) COMP-2.


CALL "CALL" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LENMAX-LEN ABSTATUS-REC.

DESCRIPTION

CALL allows a user program to synchronously send a query from a CALL delivery pointand wait for the response from the receiving service.


DELIVERY-POINT

The delivery point at which the application obtains the message from FlowBus. This mustbe the name of a CALL delivery point specified in the application profile for thisapplication.

MESSAGE-TYPE

The type of the message being sent. This must be the name of one of the message basetypes that the delivery point is configured to send.

DATA-REC

The 01 level data item data buffer containing the message to be sent and into which thereceived data will be placed. This must be large enough to contain the responsemessage.

LEN

The length of the message.

MAX-LEN


86 A2 63CD Rev01 A-51

The maximum length of data to be received.

The maximum value allowed for MAX-LEN is 32000.

FLAGS

The default flag settings used by the CALL routine are:

TPTRANTPCHANGETPBLOCKTPTIMETPNOSIGRSTRT

Refer to ABCALL for further information.

RETURN VALUES

Upon successful completion, CALL sets TP-STATUS in ABSTATUS-REC to [TPOK].When TP-STATUS in ABSTATUS-REC is set to [TPOK], DATA-REC contains themessage returned by the service, MESSAGE-TYPE contains the name of the messagetype returned by the service and LEN contains the length of the message. If DATA-RECis not large enough to receive the message, the message will be truncated and LEN willcontain the length of the message before it was truncated; that is, LEN will be greaterthan the size of DATA-REC.

ERRORS

Under the following conditions, CALL fails and sets TP-STATUS in ABSTATUS-REC toone of the following values:

[TPEINVAL ] Invalid arguments were given (for example, DELIVERY-POINT is SPACES).

[TPENOENT] The service to which this request is routed does not exist oris not a request/response service.

[TPEITYPE] The value specified in MESSAGE-TYPE is not one of theallowed message base types configured for the deliverypoint.

[TPEOTYPE] The value of MESSAGE-TYPE returned by the service is notone of the allowed message base types configured for thedelivery point .




A-52 86 A2 63CD Rev01

[TPESVCFAIL ] The service routine which received the request message (ona server SERVE delivery point) returned an error. This is anapplication level failure. MESSAGE-TYPE will containSPACES. DATA-REC will contain the error messagereturned by the application, or SPACES if there is no errormessage. If DATA-REC is not large enough to receive theerror message, the error message will be truncated and LENwill contain the length of the message before it wastruncated; that is, LEN will be greater than the size of DATA-REC.

[TPESVCERR] An error was encountered either in invoking a service routineor during its completion in CALL (for example, badarguments were passed). No reply data is returned when thiserror occurs (that is, neither DATA-REC nor MESSAGE-TYPE are not changed).

[TPEGOTSIG] A signal was received.

[TPESYSTEM] A FlowBus error has occurred. The exact nature of the errorhas been written to a log file. The content of DATA-REC isundefined. The content of MESSAGE-TYPE is undefined.


SEE ALSO

PUT, GET, PUTSVCSTART , PUTRETURN, ABCALL .

Example:

01 DELIVERY-POINT PIC X(15).01 MESSAGE-TYPE PIC X(16).01 DATA-REC. COPY USER-DATA.01 LEN PIC S9(9) COMP-2.01 MAX-LEN PIC S9(9) COMP-2.




MOVE "User Data" TO DATA-REC. MOVE "CALL_DP_NAME" TO DELIVERY-POINT. MOVE "MESSAGE-TYPE" TO MESSAGE-TYPE. MOVE LENGTH OF DATA-REC TO LEN. MOVE LENGTH OF DATA-REC TO MAX-LEN.


86 A2 63CD Rev01 A-53


CALL "CALL" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

IF NOT TPOK DISPLAY "CALL failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: CALL; delivery point; message base type

Related Information



A-54 86 A2 63CD Rev01

A.5.9 GET

NAME

GET - requests FlowBus to return a message.

SYNOPSIS


COPY USER-DATA.01 LEN PIC S9(9) COMP-2.01 MAX-LEN PIC S9(9) COMP-2.01 ABSTATUS-REC.

COPY TPSTATUS.COPY ABSTATUS.COPY ABTRANS.

CALL "GET" USING DELIVERY-POINT MESSAGE-TYPE DATA-RECLEN MAX-LEN ABSTATUS-REC.

DESCRIPTION

GET allows a user program to send a request for a notification message to a service andwait for the reply from that service at a client GET delivery point.

If GET is issued for an ASYNCHRONOUS/MIXED application instance, the GET APIreads the reply from the IDS/II database. There is no access to the service on UNIX side.If this queue is empty on GCOS 7, GET returns [TPOK] in TP-STATUS in ABSTATUS-REC, and [QMENOMSG] in APPL-RETURN-CODE in ABSTATUS-REC, even if thecorresponding queue on UNIX is not empty. A "transfer" command has to be started tofill in the GCOS 7 queue.If the Low Threshold defined for this queue is reached, atransfer is started by the LQ daemon to fill in the queue.

A combination of synchronous and asynchronous GETs on the same application instanceis illegal (see Local Queuing User's Guide).


DELIVERY-POINT

The delivery point at which the application obtains the message from FlowBus. This mustbe the name of a client GET delivery point specified in the application profile for thisapplication.


86 A2 63CD Rev01 A-55

MESSAGE-TYPE

The type of the message being requested. This must be the name of one of the messagebase types that the delivery point is configured to receive. If the delivery point isconfigured to receive any available message then this may contain SPACES.

DATA-REC

The 01 level data item into which the received message will be placed. This must belarge enough to contain the message.

MAX-LEN

The maximum length of data to be returned.


RETURN VALUES

Upon successful completion, GET sets TP-STATUS in ABSTATUS-REC to [TPOK].When TP-STATUS in ABSTATUS-REC is set to [TPOK], DATA-REC contains themessage returned, MESSAGE-TYPE contains the name of the message type returnedand LEN contains the length of the message. If DATA-REC is not large enough toreceive the message, the message will be truncated and LEN will contain the length ofthe message before it was truncated; that is , LEN will be greater than the size of DATA-REC.

ERRORS

Under the following conditions, GET fails and sets TP-STATUS in ABSTATUS-REC toone of the following values:

[TPEINVAL ] Invalid arguments were given (for example,DELIVERY-POINT is SPACES).

[TPENOENT] The service to which this request is routed does not exist oris not a request/response service.

[TPEITYPE] The value specified in MESSAGE-TYPE is not one of theallowed message base types configured for the deliverypoint DELIVERY-POINT.

[TPEOTYPE] The value of MESSAGE-TYPE returned by the service is notone of the allowed message base types configured for thedelivery point DELIVERY-POINT.




A-56 86 A2 63CD Rev01

[TPESVCFAIL ] The service routine which received the request message (ona server PUT delivery point) returned an error. This is anapplication level failure MESSAGE-TYPE will containSPACES. DATA-REC will contain the error messagereturned by the application, or SPACES if there is no errormessage. If DATA-REC is not large enough to receive theerror message, the error message will be truncated and LENwill contain the length of the message before it wastruncated; that is, LEN will be greater than the size of DATA-REC.

[TPESVCERR] An error was encountered either in invoking a service routineor during its completion in GET (for example, bad argumentswere passed). No reply data is returned when this erroroccurs (that is, neither DATA-REC nor MESSAGE-TYPE arechanged).


[TPESYSTEM] An internal error has occurred. The exact nature of the errorhas been written to a log file. The content of DATA-REC isundefined. The content of MESSAGE-TYPE is undefined.


[TPERMERR] For an ASYNCHRONOUS/MIXED application instance only.An error occured during the access to the IDS/II database.The transaction is aborted. The detailed error is written in theJOR of the TDS.

[TPEPROTO] For an ASYNCHRONOUS/MIXED application instance: anABINIT must be issued before doing ASYNCHRONOUSGETs.

SEE ALSO

PUT, CALL , PUTSVCSTART , PUTRETURN, ABCALL .


86 A2 63CD Rev01 A-57

Example:





MOVE "GET_DP_NAME" TO DELIVERY-POINT. MOVE "MESSAGE-TYPE" TO MESSAGE-TYPE. MOVE ZERO TO LEN. MOVE LENGTH OF DATA-REC TO MAX-LEN.


CALL "GET" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

IF QMENOMSG OR QMEINUSE DISPLAY "Queue is empty"

ELSE IF NOT TPOK DISPLAY "GET failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: GET; delivery point; message base type

Related Information



A-58 86 A2 63CD Rev01

A.5.10 GETRETURN

NAME

GETRETURN - finishes a server GET service.

SYNOPSIS

01 MESSAGE-TYPE PIC X(16).01 DATA-REC.

COPY USER-DATA.01 LEN PIC S9(9)COMP-2.01 ABSVCRET-REC.

COPY TPSVCRET.01 ABSTATUS-REC.


CALL "GETRETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC

DESCRIPTION

GETRETURN must be the last API call of a server GET service after it has been started.It should be called from within the same routine that was invoked in order to ensure thatcontrol is returned correctly to FlowBus. It is used to return a reply to the client PUTwhich issued the request.


MESSAGE-TYPE

This parameter must contain SPACES.

DATA-REC

The 01 level data item which will contain an error message, as necessary, to be returnedto the client PUT delivery point.

LEN

The maximum length of the error message being returned to the client PUT deliverypoint or 0 otherwise.

The maximum value taken into account for LEN is 32000.


86 A2 63CD Rev01 A-59



TPSUCCESS The service has terminated successfully. If data is present,then it will be sent (barring any failures processing thereturn). If the caller is in transaction mode, thenGETRETURN places the caller's portion of the transaction ina state such that it can be committed when the transactionultimately commits. Note that a call to GETRETURN doesnot necessarily end a transaction. Also, even though thecaller indicates success, if there are any outstanding replies,if any work done within the service caused its transaction tobe marked abort-only, then a failed message is sent. In thiscase the recipient of the reply receives a TPESVCERRindication. Note that if a transaction becomes abort-onlywhile in the service routine for any reason, then TP-RETURN-VAL should be set to TPFAIL .

TPFAIL The service has terminated unsuccessfully from anapplication standpoint. An error will be reported to theprogram receiving the reply. That is, the call to get the replywill fail and the recipient receives a [TPSVCERR] indication.If the caller is in transaction mode, then GETRETURN marksthe transaction as abort-only (note that the transaction mayalready be marked abort-only). Barring any failures inprocessing the return, the caller's data is sent, if present.One reason for not sending the caller's data is when atransaction timeout has occurred. In this case, the programwaiting for the reply will receive an error of [TPETIME].




This parameter specifies an application-defined return code that may be sent to thereceiving application. This code is sent regardless of the setting of TP-RETURN-VALprovided a reply can be successfully sent. A reply can be sent if the receiving call returnssuccess or [TPESVCFAIL ]. The value of APPL-CODE is available to the receivingapplication in APPL-RETURN-CODE in ABSTATUS-REC.

RETURN VALUES

GETRETURN returns control to the service routine which must execute an EXITPROGRAM statement immediately. No value is returned to the caller. If a service routinereturns without using GETRETURN followed by EXIT PROGRAM, the behaviour of thesystem is undefined.

An error message should be returned to the client PUT delivery point only when TPFAILis returned.


A-60 86 A2 63CD Rev01

SEE ALSO

PUTRETURN, SERVERETURN, GETSVCSTART , PUT, ABRETURN .

Example:

PROGRAM-ID. SERVEGET.






MOVE "SERVEGET" TO DELIVERY-POINT. MOVE LENGTH OF DATA-REC TO MAX-LEN.


CALL "GETSVCSTART" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC. IF NOT TPOK DISPLAY "GETSVCSTART failed. The error returned was " TP-STATUS

SET TPFAIL TO TRUE MOVE ZERO TO APPL-CODE IN ABSVCRET-REC MOVE ZERO TO LEN MOVE SPACES TO MESSAGE-TYPE


EXIT PROGRAM.

SET TPSUCCESS TO TRUE. MOVE ZERO TO APPL-CODE IN ABSVCRET-REC. MOVE ZERO TO LEN. MOVE SPACES TO MESSAGE-TYPE.

CALL "GETRETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC.

EXIT PROGRAM.


86 A2 63CD Rev01 A-61

SUGGESTED READING



Related Information



A-62 86 A2 63CD Rev01

A.5.11 GETSVCSTART

NAME

GETSVCSTART - starts a server GET service by receiving a notification message fromFlowBus.

SYNOPSIS




CALL "GETSVCSTART" USING DELIVERY-POINT MESSAGE-TYPE DATA-RECLEN MAX-LEN ABSTATUS-REC.

DESCRIPTION

GETSVCSTART must be the first API call of a server GET service after it has beenstarted. It is used to obtain the notification message from FlowBus.


DELIVERY-POINT

The delivery point at which the application receives the notification message fromFlowBus. This must be the name of a server GET delivery point specified in theapplication profile for this application.

MAX-LEN

The maximum length of the message to be received.



86 A2 63CD Rev01 A-63

RETURN VALUES

Upon successful completion, GETSVCSTART sets TP-STATUS in ABSTATUS-REC to[TPOK]. When TP-STATUS in ABSTATUS-REC is set to [TPOK], DATA-REC containsthe message returned by the service, MESSAGE-TYPE contains the name of themessage type returned by the service and LEN contains the length of the returnedmessage. If DATA-REC is not large enough to receive the message, the message will betruncated and LEN will contain the length of the message before it was truncated; that is, LEN will be greater than the size of DATA-REC.

ERRORS

Under the following conditions, GETSVCSTART fails and sets TP-STATUS inABSTATUS-REC to one of the following values:


[TPEPROTO] GETSVCSTART was called in an improper context.

[TPESYSTEM] A FlowBus error has occurred. The exact nature of the errorhas been written to a log file.


SEE ALSO

PUTSVCSTART , SERVESTART , GETRETURN, PUT, ABSVCSTART .

Example:

PROGRAM-ID. SERVEGET.






A-64 86 A2 63CD Rev01


MOVE "SERVEGET" TO DELIVERY-POINT. MOVE LENGTH OF DATA-REC TO MAX-LEN.


CALL "GETSVCSTART" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

IF NOT TPOK DISPLAY "GETSVCSTART failed. The error returned was " TP-STATUS



EXIT PROGRAM.

SET TPSUCCESS TO TRUE. MOVE ZERO TO APPL-CODE IN ABSVCRET-REC. MOVE ZERO TO LEN. MOVE SPACES TO MESSAGE-TYPE.

CALL "GETRETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC.

EXIT PROGRAM.

SUGGESTED READING


Glossary Terms: GET; SERVE.

Related Information



86 A2 63CD Rev01 A-65

A.5.12 PUT

NAME

PUT - delivers a notification message to FlowBus. No reply is expected.

SYNOPSIS




CALL "PUT" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

DESCRIPTION

PUT allows a user program to send a notification type message from a client PUTdelivery point. If the PUT is issued for an ASYNCHRONOUS/MIXED application instancethe message is simply stored in the IDS/II database, and it will be transferredasynchronously to its destination on the UNIX side.

The messages are stored in the IDS/II database, in the message queue of the LQinstance. A maximum number of messages for this LQ Instance has been defined atcreation time, as well as a High Threshold. If the maximum number is reached, the nextmessage is not registered in the database and an error is returned. If the High Thresholdis reached, a transfer is started by the LQ daemon to empty the queue.

The combination of synchronous and asynchronous PUTs on the same applicationinstance is illegal. (See Local Queuing User's Guide).


DELIVERY-POINT

The delivery point at which the application passes the message to FlowBus. This mustbe the name of a client PUT delivery point specified in the application profile for thisapplication.

MESSAGE-TYPE

The base type of the message being sent. This must be the name of one of the messagebase types that the delivery point is configured to send.


A-66 86 A2 63CD Rev01

DATA-REC

The 01 level data item containing the message to be sent.

LEN

The length of the message.

MAX-LEN

The maximum length of an error message which may be received.


RETURN VALUES

Upon successful completion, PUT sets TP-STATUS in ABSTATUS-REC to [TPOK].When TP-STATUS in ABSTATUS-REC is set to [TPOK], MESSAGE-TYPE will containSPACES, LEN will contain 0 and DATA-REC will be undefined.

ERRORS

Under the following conditions, PUT fails and sets TP-STATUS in ABSTATUS-REC toone of the following values:



[TPEITYPE] The value specified in MESSAGE-TYPE is not one of theallowed message base types configured for the deliverypoint DELIVERY-POINT.



[TPESVCFAIL ] The service routine which received the notification message(on a server GET delivery point) returned an error. This is anapplication level failure. MESSAGE-TYPE will containSPACES. DATA-REC will contain the error messagereturned by the application, or SPACES if there is no errormessage. If DATA-REC is not large enough to receive theerror message, the error message will be truncated and LENwill contain the length of the message before it wastruncated; that is, LEN will be greater than the size of DATA-REC.


86 A2 63CD Rev01 A-67

[TPESVCERR] An error was encountered either in invoking a service routineor during its completion in PUT (for example, bad argumentswere passed). No reply data is returned when this erroroccurs. Neither DATA-REC nor MESSAGE-TYPE arechanged).


[TPESYSTEM] A FlowBus error has occurred. The exact nature of the errorhas been written to a log file. The content of DATA-REC isundefined. The content of MESSAGE-TYPE is undefined.


[TPERMERR] For ASYNCHRONOUS/MIXED application only. An erroroccured during the IDS/II datatabase access. The transactionis aborted. The exact nature of the IDS/II is written to theJOR of the TDS.

[TPEPROTO] For an ASYNCHRONOUS/MIXED application instance: anABINIT must be issued before doing ASYNCHRONOUSPUTs.

SEE ALSO

GET, CALL , GETSVCSTART , GETRETURN, ABCALL .


A-68 86 A2 63CD Rev01

Example:





MOVE "User Data" TO DATA-REC. MOVE "PUT_DP_NAME" TO DELIVERY-POINT. MOVE "MESSAGE-TYPE" TO MESSAGE-TYPE. MOVE LENGTH OF DATA-REC TO LEN. MOVE LENGTH OF DATA-REC TO MAX-LEN.


CALL "PUT" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

IF NOT TPOK DISPLAY "PUT failed. The error returned was " TP-STATUS.

SUGGESTED READING


Glossary Terms: PUT; delivery point; message base type

Related Information



86 A2 63CD Rev01 A-69

A.5.13 PUTRETURN

NAME

PUTRETURN - finishes a server PUT service by delivering a notification message toFlowBus.

SYNOPSIS


COPY USER-DATA.01 LEN PIC S9(9) COMP-2.01 ABSVCRET-REC.



CALL "PUTRETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC.

DESCRIPTION

PUTRETURN must be the last API call of a server PUT service after it has been started.It should be called from within the same routine that was invoked in order to ensure thatcontrol is returned correctly to FlowBus. It is used to return a reply to the client GETwhich issued the request.


MESSAGE-TYPE


DATA-REC


LEN

The length of the outgoing message.



A-70 86 A2 63CD Rev01



TPSUCCESS The service has terminated successfully. If data is present,then it will be sent (barring any failures processing thereturn). If the caller is in transaction mode, thenPUTRETURN places the caller's portion of the transaction ina state such that it can be committed when the transactionultimately commits. Note that a call to PUTRETURN doesnot necessarily end a transaction. Also, even though thecaller indicates success, if there are any outstanding replies,if any work done within the service caused its transaction tobe marked abort-only, then a failed message is sent. In thiscase the recipient of the reply receives a TPESVCERRindication. Note that if a transaction becomes abort-onlywhile in the service routine for any reason, then TP-RETURN-VAL should be set to TPFAIL .

TPFAIL The service has terminated unsuccessfully from anapplication standpoint. An error will be reported to theprogram receiving the reply. That is, the call to get the replywill fail and the recipient receives a [TPSVCERR] indication.If the caller is in transaction mode, then PUTRETURN marksthe transaction as abort-only (note that the transaction mayalready be marked abort-only). Barring any failures inprocessing the return, the caller's data is sent, if present.One reason for not sending the caller's data is when atransaction timeout has occurred. In this case, the programwaiting for the reply will receive an error of [TPETIME].

NOTE: that MESSAGE-TYPE must be SPACES when TP-RETURN-VAL is set toTPFAIL .






86 A2 63CD Rev01 A-71

RETURN VALUES

PUTRETURN returns control to the service routine which must execute an EXITPROGRAM statement immediately. No value is returned to the caller. If a service routinereturns without using PUTRETURN followed by EXIT PROGRAM, the behaviour of thesystem is undefined.

SEE ALSO

GETRETURN, SERVERETURN, PUTSVCSTART , GET, ABRETURN .

Example:

PROGRAM-ID. SERVEPUT.

01 DELIVERY-POINT PIC X(15).01 MESSAGE-TYPE PIC X(16).01 DATA-REC. COPY USER-DATA.01 LEN PIC S9(9) COMP-2.





MOVE "SERVEPUT" TO DELIVERY-POINT. SET FLOWBUS-TRANS-STORAGE IN ABSTATUS-REC TO ADDRESS OF FLOWBUS-TRANS.

CALL "PUTSVCSTART" USING DELIVERY-POINT MESSAGE-TYPE ABSTATUS-REC.

IF NOT TPOK DISPLAY "PUTSVCSTART failed. The error returned was " TP-STATUS

SET TPFAIL TO TRUE MOVE ZERO TO APPL-CODE IN ABSVCRET-REC MOVE ZERO TO LEN MOVE SPACES TO MESSAGE-TYPE CALL "PUTRETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC

EXIT PROGRAM.


A-72 86 A2 63CD Rev01

SET TPSUCCESS TO TRUE. MOVE ZERO TO APPL-CODE IN ABSVCRET-REC. MOVE "User Data" TO DATA-REC. MOVE LENGTH OF DATA-REC TO LEN. MOVE "MESSAGE-TYPE" TO MESSAGE-TYPE.


EXIT PROGRAM.

SUGGESTED READING



Related Information



86 A2 63CD Rev01 A-73

A.5.14 PUTSVCSTART

NAME

PUTSVCSTART - starts a server PUT service by receiving a request for a messagefrom FlowBus.

SYNOPSIS

01 DELIVERY-POINT PIC X(15).01 MESSAGE-TYPE PIC X(16).01 ABSTATUS-REC.


CALL "PUTSVCSTART" USING DELIVERY-POINT MESSAGE-TYPEABSTATUS-REC.

DESCRIPTION

PUTSVCSTART must be the first API call of a server PUT service after it has beenstarted. It is used to obtain the requested message type from FlowBus.


DELIVERY-POINT

The delivery point at which the application obtains the request from FlowBus. This mustbe the name of a server PUT delivery point specified in the application profile for thisapplication.

RETURN VALUES

Upon successful completion, PUTSVCSTART sets TP-STATUS in ABSTATUS-REC to[TPOK]. When TP-STATUS in ABSTATUS-REC is set to [TPOK], MESSAGE-TYPEcontains the name of the message type returned by the service. If MESSAGE-TYPEcontains SPACES then any message type can be returned on the correspondingPUTRETURN.


A-74 86 A2 63CD Rev01

ERRORS

Under the following conditions, PUTSVCSTART fails and sets TP-STATUS inABSTATUS-REC to one of the following values:



[TPEPROTO] PUTSVCSTART was called in an improper context.

[TPESYSTEM] An internal error has occurred. The exact nature of the errorhas been written to a log file.


SEE ALSO

GETSVCSTART , SERVESTART , PUTRETURN, GET, ABSVCSTART .

Example:

PROGRAM-ID. SERVEPUT.

01 DELIVERY-POINT PIC X(15).01 MESSAGE-TYPE PIC X(16).01 DATA-REC. COPY USER-DATA.01 LEN PIC S9(9) COMP-2.





MOVE "SERVEPUT" TO DELIVERY-POINT. SET FLOWBUS-TRANS-STORAGE IN ABSTATUS-REC TO ADDRESS OF FLOWBUS-TRANS.

CALL "PUTSVCSTART" USING DELIVERY-POINT MESSAGE-TYPE ABSTATUS-REC.

IF NOT TPOK DISPLAY "PUTSVCSTART failed. The error returned was " TP-STATUS SET TPFAIL TO TRUE MOVE ZERO TO APPL-CODE IN ABSVCRET-REC MOVE ZERO TO LEN MOVE SPACES TO MESSAGE-TYPE


86 A2 63CD Rev01 A-75

CALL "PUTRETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC

EXIT PROGRAM.



EXIT PROGRAM.

SUGGESTED READING


Glossary Terms: PUT; server.

Related Information



A-76 86 A2 63CD Rev01

A.5.15 SERVERETURN

NAME

SERVERETURN - finishes a SERVE service by delivering a notification message toFlowBus.

SYNOPSIS


COPY USER-DATA.01 LEN PIC S9(9) COMP-2.01 ABSVCRET-REC.



CALL "SERVERETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC.

DESCRIPTION

SERVERETURN must be the last API call of a SERVE service after it has been started.It should be called from within the same routine that was invoked in order to ensure thatcontrol is returned correctly to FlowBus. It is used to return a reply to the CALL whichissued the request or as a request to another SERVE delivery point.


MESSAGE-TYPE


DATA-REC


LEN

The length of the outgoing message.



86 A2 63CD Rev01 A-77



TPSUCCESS The service has terminated successfully. If data is present,then it will be sent (barring any failures processing thereturn). If the caller is in transaction mode, thenSERVERETURN places the caller's portion of the transactionin a state such that it can be committed when the transactionultimately commits. Note that a call to SERVERETURN doesnot necessarily end a transaction. Also, even though thecaller indicates success, if there are any outstanding replies,if any work done within the service caused its transaction tobe marked abort-only, then a failed message is sent. In thiscase the recipient of the reply receives a TPESVCERRindication. Note that if a transaction becomes abort-onlywhile in the service routine for any reason, then TP-RETURN-VAL should be set to TPFAIL .

TPFAIL The service has terminated unsuccessfully from anapplication standpoint. An error will be reported to theprogram receiving the reply. That is, the call to get the replywill fail and the recipient receives a [TPSVCERR] indication.If the caller is in transaction mode, then SERVERETURNmarks the transaction as abort-only (note that the transactionmay already be marked abort-only). Barring any failures inprocessing the return, the caller's data is sent, if present.One reason for not sending the caller's data is when atransaction timeout has occurred. In this case, the programwaiting for the reply will receive an error of [TPETIME].

NOTE: that MESSAGE-TYPE must be SPACES when TP-RETURN-VAL is set toTPFAIL .






A-78 86 A2 63CD Rev01

RETURN VALUES

SERVERETURN returns control to the service routine which must execute an EXITPROGRAM statement immediately. No value is returned to the caller. If a service routinereturns without using SERVERETURN followed by EXIT PROGRAM, the behaviour ofthe system is undefined.

SEE ALSO

PUTRETURN, GETRETURN, SERVESTART , ABRETURN , CALL .

Example:

PROGRAM-ID. SERVE.






MOVE "SERVE" TO DELIVERY-POINT. MOVE LENGTH OF DATA-REC TO MAX-LEN.


CALL "SERVESTART" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

IF NOT TPOK DISPLAY "SERVESTART failed. The error returned was " TP-STATUS


CALL "SERVERETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC

EXIT PROGRAM.


86 A2 63CD Rev01 A-79


CALL "SERVERETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC.

EXIT PROGRAM.

SUGGESTED READING



Related Information



A-80 86 A2 63CD Rev01

A.5.16 SERVESTART

NAME

SERVESTART - starts a SERVE service by receiving a query message from FlowBus.

SYNOPSIS




CALL "SERVESTART" USING DELIVERY-POINT MESSAGE-TYPE DATA-RECLEN MAX-LEN ABSTATUS-REC.

DESCRIPTION

SERVESTART must be the first API call of a SERVE service after it has been started. Itis used to obtain the query message from FlowBus.


DELIVERY-POINT

The delivery point at which the application receives the query message from FlowBus.This must be the name of a SERVE delivery point specified in the application profile forthis application.

MAX-LEN

The maximum length of the message to be received.



86 A2 63CD Rev01 A-81

RETURN VALUES

Upon successful completion, SERVESTART sets TP-STATUS in ABSTATUS-REC to[TPOK]. When TP-STATUS in ABSTATUS-REC is set to [TPOK], DATA-REC containsthe received message, MESSAGE-TYPE contains the name of the message typereturned by the service and LEN contains the length of the received message. If DATA-REC is not large enough to receive the message, the message will be truncated and LENwill contain the length of the message before it was truncated; that is, LEN will be greaterthan the size of DATA-REC.

ERRORS

Under the following conditions SERVESTART fails and sets TP-STATUS in ABSTATUS-REC to one of the following values:



[TPEPROTO] SERVESTART was called in an improper context.

[TPESYSTEM] A FlowBus error has occurred. The exact nature of the errorhas been written to a log file. The content of DATA-REC isundefined.

[TPEOS] A FlowBus error has occurred.

SEE ALSO

PUTSVCSTART , GETSVCSTART , SERVERETURN, ABSVCSTART , CALL .

Example:

PROGRAM-ID. SERVE.



01 ABSTATUS-REC. COPY TPSTATUS. COPY ABSTATUS. COPY ABTRANS.LINKAGE SECTION. COPY TDS-STORAGE. COPY CONSTANT-STORAGE.01 TRANSACTION-STORAGE. 02 FLOWBUS-TRANS. COPY FLOWBUS-TRANS-STORAGE.


A-82 86 A2 63CD Rev01


MOVE "SERVE" TO DELIVERY-POINT. MOVE LENGTH OF DATA-REC TO MAX-LEN. SET FLOWBUS-TRANS-STORAGE IN ABSTATUS-REC TO ADDRESS OF FLOWBUS-TRANS.

CALL "SERVESTART" USING DELIVERY-POINT MESSAGE-TYPE DATA-REC LEN MAX-LEN ABSTATUS-REC.

IF NOT TPOK DISPLAY "SERVESTART failed. The error returned was " TP-STATUS


CALL "SERVERETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC

EXIT PROGRAM.

SET TPSUCCESS TO TRUE. MOVE ZERO TO APPL-CODE IN ABSVCRET-REC. MOVE "User Data" TO DATA-REC. MOVE LENGTH OF DATA-REC TO LEN. MOVE "MESSAGE-TYPE" TO MESSAGE-TYPE. CALL "SERVERETURN" USING MESSAGE-TYPE DATA-REC LEN ABSVCRET-REC ABSTATUS-REC.

EXIT PROGRAM.

SUGGESTED READING


Glossary Terms: CALL; SERVE.

Related Information


86 A2 63CD Rev01 B-1

B. Application Instances

B.1 WHAT THIS APPENDIX IS ABOUT

This appendix tells you about application instances. An application instance includes allthe information that FlowBus requires to route a message to the executable application.

The appendix covers these topics:

Application instances


B-2 86 A2 63CD Rev01

B.2 APPLICATION INSTANCES

An application instance adds physical attributes to the logical attributes of an applicationprofile. The physical attributes contain information specific to the computer andtransaction monitor on which an instance of an application runs. Network models containlinks between application instances.

You must create an application instance for each executable application that interactsover FlowBus. You can create more than one instance of the same application which letsyou have, for example:

• One application instance on a computer that runs all the time

• Another instance of the same application on a second computer that is less busy atpeak times

The following scenario is another example of application instances:

• The application TAX running on the computer CENTRAL1 under the GCOS 7operating system is an application instance

• The same application TAX running on the computer LOCAL1 under the UNIXoperating system is a second application instance. It is also a second instance of thesame application.

• The application CREDIT running on the same computer LOCAL1 under the UNIXoperating system is a third application instance. It is an instance of anotherapplication.

An application instance has:

• An identifier

• An application profile

• An optional run command

• Delivery point mappings

Application Instances

86 A2 63CD Rev01 B-3

B.2.1 Application Instance Identifier

You must specify an identifier for the application instance. The maximum length of anidentifier is 32 characters. Each character must be either alphanumeric or minus (-) orunderscore (_). Embedded spaces are not allowed. For ease of use, you may wish to usean identifier which refers to the name of the application profile and the transactionmonitor on which the instance runs. For example:

• AGENTTDS

• cred-tuxedo

• OPEN_CICS

An application instance is not valid unless it has a valid identifier.

B.2.2 Application Profile

Each application instance is based on an application profile. The instance has thedelivery points associated with the application profile. Delivery points carry the messagebase types associated with them in the application profile.

The application instance must contain the code for each delivery point. Differentinstances of the same application do not need to be coded in the same language. Onlythe delivery point names and delivery point types need to be the same. Otherwise, theapplication can do any processing required.

The application profile must be available (using the GUI administration tool) before youcan base an instance on it.

B.2.3 Run Command

The run command specifies the command line to start the application. FlowBus uses therun command when a queue that the application reads from reaches its threshold.Passive application instances require a run command. Other types of instance do notrequire a run command.

The run command must consist of the precise string required to start the application. Itmay be used by the queueing service to start up a client application to read from aqueue.

For TDS applications the RUN command has the following format:

T<space character> CORRESPONDANT<space character>TX-NAME<spacecharacter>TX-DATA


B-4 86 A2 63CD Rev01

Where :

T Upper case letter T.CORRESPONDANT Name of the TDS correspondant the transaction will be

spawned to.TX-NAME Name of the transaction to be started.TX-DATA The data to be passed to the transaction given in TX-NAME.

The run command must consist of not more than 100 alphanumeric character or spaces.

The following are example run commands:

• T DUMMY OPERS QUEUE1The transaction OPERS is spawned to the DUMMY user. The data received by thetransaction is the string "QUEUE1".

• T TDSALS CUST BULL 2000The transaction CUST is spawned to the user TDSALS. The data received by thetransaction is the string "BULL 2000". The user TDSALS could be a named virtualcorrespondant.

• T DUMMY MYTXThe transaction MYTX is spawned to the DUMMY user, no data is received by thetransaction.

B.2.4 Run Server Group

Each application instance that has a run command must also specify the name of the runserver group. The run server group identifies the computer on which the run command isto be executed. On UNIX computers the run server group name must be the name of anadministrative server group which contains the application loader server (BABALS). Seethe FlowBus Configuration Tool User's Guide for details. On non-UNIX computers the runserver group name must be the name of the TUXEDO server group which is configuredto communicate with the remote computer (See the chapter on building TUXEDO clientsand servers in this manual).

For more information on the configuration of the above servers please refer to theFlowBus System Administration and Configuration Guide.

Application Instances

86 A2 63CD Rev01 B-5

B.2.5 Delivery Point Mappings

Delivery point names are logical names used in the application code. These arespecified in the application profile. Delivery points can be mapped onto real services ifthe names of the services differ from the delivery point names.

For GCOS 7 there are two solutions which are mutually exclusive:

1. If ALL the delivery points on ALL the applications are the same as the GCOS 7transaction names then:

- all the delivery points can be mapped onto the service BAB_SVC (for thisservice, see the FlowBus System Administration and Configuration Guide,chapter Configuring GCOS 7 Administrative Applications under UNIX)

- BAB_SVC is advertised as a service in the TUXEDO configuration fileUBBCONFIG

2. If the name of any of the delivery points differs from the transaction name then:

- all the delivery points must be mapped onto the transaction names

- all the transaction names must be advertised as services in the TUXEDOconfiguration file UBBCONFIG

- a SERVICES environment variable must be configured for the GCOS 7 servergroup. This must be a comma separated list of transaction names. Forexample,

SERVICES=DEBIT, CREDIT

The server group name for the applications instance must be the name of the TUXEDOserver group which is configured to communicate with the remote computer.


B-6 86 A2 63CD Rev01

86 A2 63CD Rev01 C-1

C. The Example Application (sampleapp)

C.1 WHAT THIS APPENDIX IS ABOUT

This appendix tells you about the example application supplied with FlowBus.

The appendix covers these topics:

The Example Application (sampleapp )

This sampleapp does not use Local Queuing. A specific lqsample application isdescribed in an appendix of the Local Queuing User's Guide.


C-2 86 A2 63CD Rev01

C.2 THE EXAMPLE APPLICATION (SAMPLEAPP)

Sampleapp is a simple and easy to understand example application supplied with theFlowBus software in the directory sampleapp on UNIX and in the GCOS 7 source library<dir>.flowbus.sample.sllib. Where <dir> is the top level directory name used at the timeof installing FlowBus on GCOS 7.

The sample application has been designed:

• to demonstrate most of the functionality provided by the FlowBus API functions

• to show how to configure FlowBus

• to show how to build and execute user applications

• to provide a means of verifying the correct installation of FlowBus

Sampleapp is based on a banking scenario in which a customer applies for a newsavings account and makes an initial deposit . When the savings account is opened, thecustomer is informed of the account number and the initial deposit is credited to theaccount. Details of the account and all transactions are written to log files so that thebank branch management can handle any queries raised by the customer on the way theaccount is being managed.

A detailed description of sampleapp is given in the FlowBus Application Administrationand Integration Guide

A description of how to configure FlowBus, including details of the UNIX environmentvariables, is given in the FlowBus System Administration and Configuration Guide.

C.2.1 Network Model Symbols

The symbols shown in figure C-1 in this section are used on network model diagramsand illustrations in the rest of this guide. These symbols differ from the symbols that yousee when you use the FlowBus Configuration Tool to create and modify network models.

C.2.1.1 Sampleapp Network Models

Figures C-2 and C-3 show the network models supplied with sampleapp . Figure C-2shows the network model which uses the message transformation service and figure C-3shows the network model which uses an application to perform the messagetransformation. The name of the first network model is sampleapp-host and the nameof the second is sampleapp-host2 . One of these two network models must have beenpreviously made available with the FlowBus Configuration Tool (GUI).

These network models link all the applications in real time and any of the applicationinstances can be instantiated on any valid platform.

The Example Application (sampleapp)

86 A2 63CD Rev01 C-3

Q ueue

C lient P U Tdelivery point

C lient G ETdelivery point

C lien t C A LLde livery point

Server P U Tdelivery point

S erver G ETdelivery point

Server S ER V Edelivery point

P U Ttransform ation

Figure C-1. Network Model Symbols

The names shown in figures C-2 and C-3 are the application instance names. Therelationship between the application instance names and the TDS transaction names is:

Instance Name Transaction Name

NEW_AC NEWACOPERS CENTRLOPAC_MAN OPENACAC_GEN NEWACNOPROC_DEP DEPOSITBRNCH_MAN LOCALOP


C-4 86 A2 63CD Rev01

In figure C-3, NEW_AC opens a new savings account with an initial deposit by:

• displaying a form for the user to enter customer details

• requesting the opening of a new account by sending a query containing the customerdetails to AC_MAN

AC_MAN gets a new account number from AC_GEN. AC_MAN then returns accountdetails, including the new account number, to NEW_AC.

• sending a notification containing an amount to be deposited and account details toPROC_DEP.

PROC_DEP sends notifications to BRNCH_MAN, which records the deposit in the logfile <dir>.LOCLOG, and to the queue opersQ. OPERS reads from opersQ and recordsthe deposit in the log file <dir>.CENLOG.

The application in figure C-2 is almost identical to the application in figure C-3. Thedifference is the replacement of the application PROC_DEP by the messagetransformation service DEP_TO_OP.

The tasks required on both UNIX and GCOS 7 to run the sample application aredescribed in the following paragraphs.


86 A2 63CD Rev01 C-5

N E W _ A C

openac

depositAC_MAN

opennew_ac_no

AC_GEN

emitDEP_TO_OP

BRNCH_MAN

ops OPERS

incoming

opersQ

ac_dets

cust_dets

ac_no

first_dep

central_op

local_op

central_op

Figure C-2. Network Model using the Message Transformation Service (sampleapp-host)


C-6 86 A2 63CD Rev01

N E W _ A C

openacdeposit

AC_MAN

open

new_ac_no

AC_GEN

emitPROC_DEP

BRNCH_MAN

ops OPERS

incoming

opersQ

ac_dets

cust_dets

ac_no

first_dep

central_op

local_op

central_op

rec out

Figure C-3. Network Model without the Message Transformation Service (sampleapp-host2)


86 A2 63CD Rev01 C-7

C.2.2 UNIX sampleapp Directory Structure

Figure C-4 shows the directory structure under the sampleapp directory, which issubordinate to the root directory for your FlowBus software.

sampleapp/

cl ients servers forms include db

Figure C-4. Directory structure under sampleapp

The sample application sources are written in COBOL. For those users who will not beusing the FlowBus UNIX COBOL API and may not have a Micro Focus COBOLcompiler, the application executable files are provided in <BAB_ROOTDIR>/bin.

C.2.3 GCOS 7 sampleapp Directory Structure

All the necessary sources for building sampleapp are delivered in the GCOS 7 sourcelibrary <dir>.flowbus .sample.sllib.

C.2.4 GCOS 7 sampleapp clients

The following clients are used. Look at the source files in the sampleapp library onGCOS 7 for a complete description of how they are implemented.

• Transaction name: NEWAC

Source file: NEWAC01

Purpose This client represents a user dialogue for the opening of anew savings account. It captures customer details beforeperforming a CALL to create a new account. When aresponse giving the account details is received, a PUT isperformed to make the initial deposit into the new account.


C-8 86 A2 63CD Rev01

• Transaction name: CENTRLOP

Source file: OPERS01

Purpose: This client represents a central operations processingapplication. It takes incoming operations and processes themby logging information in a file. The next operationnotification message is obtained by repeatedly performing aGET.

C.2.5 GCOS 7 sampleapp Servers

The following servers are used. Look at the source files in the sampleapp library onGCOS 7 for a complete description of how they are implemented.

• Transaction name: OPENAC

Source files: OPENAC

Purpose: This server performs account management for newaccounts. The server receives a message containingcustomer details from a client. It calls another service toobtain a new account number in order to set up the accountdetails which are returned to the client in the responsemessage.

• Transaction name: LOCALOP

Source files: LOCALOP

Purpose: This server performs branch management. It receivesmessages describing operations and processes them bylogging the details to a file.

• Transaction name: NEWACNO

Source files: NEWACNO

Purpose: This server supplies new account numbers.

• Transaction name: DEPOSIT

Source files: DEPOSIT

Purpose: This server mimics the transformation and diffusion of afirst_dep message into a local and central operationnotification. It obtains the incoming message and converts itinto two outgoing messages; performing a PUT for eachoutgoing message.


86 A2 63CD Rev01 C-9

C.2.6 GCOS 7 sampleapp Data Files

The following data files are used:

• account identifier file (<dir>.ACCOUNT)This file is managed by the transaction NEWACNO and holds information about thenext account identifier to be issued when a new account is opened.

• account detail file (<dir>.SACCOUNT)This file is managed by the transaction OPENAC and holds information about theaccount (account number, client name etc).

• local operation log file (<dir>.LOCLOG)This file is managed by the transaction LOCALOP and holds information about thelocal operations performed.

• central operation log file (<dir>.CENLOG)This file is managed by the transaction CENTRLOP and holds information about thecentral operations performed.

C.2.7 UNIX sampleapp Transformation Server

The following transformation server is used. Look at the source files in the serversdirectory for a complete description of how it is implemented.

Executable file: DEP_TO_OP

Source files: dep_to_local.cbl (convert first_dep messages to central_opmessages)

dep_to_central.cbl (convert first_dep messages to local_opmessages)

Purpose: This transformation performs a transformation and diffusion of afirst_dep message into a local and central operation notification. Thiscan be used instead of the PROC_DEP server when the messagetransformation service is available.

C.2.8 UNIX sampleapp Queues

The following queue is used:

opersQ

This queue is implemented using the /Q component of TUXEDO.


C-10 86 A2 63CD Rev01

C.2.9 How to Build sampleapp on UNIX

The following steps explain how to build sampleapp when your directory only containsthe sampleapp files as delivered with FlowBus.

Step 1:

Make a directory for sampleapp and copy the sampleapp files and directories to it:

cp -r <BAB_ROOTDIR>/sampleapp myapp

This is recommended as you will be editing some of the files contained in this directory,and it is better to begin with a copy of the files rather than the originals delivered withFlowBus.

Step 2:

Change to your sampleapp directory:

cd myapp

Step 3:

Execute the command ls to list the supplied files and directories:

UBBCONFIG.gcos7 the TUXEDO configuration file for running the application onGCOS 7.

crlog a script that creates the TUXEDO transaction log.

crque a script that defines the queue space and queues for theapplication.

db a directory containing a pre-loaded configuration database.The database contains network models corresponding to thesample application.

env_g7 a file containing environment variables used by FlowBusGCOS 7 export API servers.

envfile a file containing environment settings used by FlowBusadministrative applications.

rmqipc a script for removing the IPC resources associated with thequeue space on application shutdown.

sedscript.gcos a script for setting user-specific values in the filesUBBCONFIG.gcos7, crque, env_g7, envfile andsetvar .

setvar a script which sets environment variables.


86 A2 63CD Rev01 C-11

NOTE: that the above is not an exhaustive list of files delivered in the sampleappdirectory, just those required to build the UNIX components needed to run thesampleapp on GCOS 7.

Step 4:

The files UBBCONFIG.gcos7 , crque , env_g7 , envfile and setvar have user-specific entries that must be set to your own values. The text to be replaced in each fileis enclosed in angle brackets e.g. <IPCKEY for TUXEDO> . The file sedscript.gcosis provided to perform the modifications to these files automatically.

Edit sedscript.gcos replacing the "REPLACE_ME" text with the following values:

uname of site1 this is the name of your master UNIXcomputer. It is the output of the UNIXcommand uname -n .

Full path name of TUXDIR the full path name of the directory underwhich your TUXEDO software is installed.

Full path name of APPDIR the full path name of the applicationdirectory created in step 1.

Full path name of BAB_ROOTDIR the full path name of the directory underwhich your FlowBus software is installed.

Full path name of COBDIR the full path name of the directory underwhich your Micro Focus COBOL software isinstalled.

IPCKEY for TUXEDO a unique numeric key for TUXEDO's sharedUNIX resources. Must be between 32,768and 262,143.

IPCKEY for /Q a unique numeric key for TUXEDO /Q'sshared UNIX resources. Must be between32,768 and 262,143.

IPCKEY for BUS a unique numeric key for FlowBus's sharedUNIX resources. Must be between 32,768and 262,143. This number will become theenvironment variable BAB_IPCKEY.

Please refer to your UNIX documentation for a description of IPC keys.

SYMBDESTNAME XCP2 symbolic destination name (TDS).

DACSID Full path name of the XCP2 side informationfile.

Step 5:

Type:

./sedscript.gcos


C-12 86 A2 63CD Rev01

to perform the file modifications.

Step 6:

Type:

. ./setvar

to set up your FlowBus and TUXEDO environment.

Step 7:

Type:

tmloadcf -y UBBCONFIG.gcos7

to build the TUXEDO binary configuration file, TUXCONFIG.

NOTES: 1. you must delete and recreate the transaction log and queue space,as explained in steps 8 and 9, whenever you rebuild TUXCONFIG.

2. BABC7 and BABS7 must have been built before (see chapter 6.2).

Step 8:

Type:

crlog

to create the transaction log used by the application.

Step 9:

Type:

crque

to create the queue space used by the application.

This command generates the following warning message in the TUXEDO user log:

Q_CAT:1496:WARN xa_open() - error queue errque not created

where errque is the name of the error queue specified for the qspace.

The warning message is expected output from TUXEDO /Q and can be ignored.


86 A2 63CD Rev01 C-13

C.2.10 How to Build sampleapp on GCOS 7

It is assumed that the administrator is familiar with TDS, GCOS 7 Library maintenanceand IOF.

Step 1:

Create a TDS generation member 'STDS' which contains the file and transactiondefinitions needed to run the sampleapp. This can be achieved in two ways:

• By using the example 'STDS' member delivered in the sampleapp library to build anew TDS called BUSI, for example.

• Merge the example 'STDS' member delivered in the sampleapp library with an alreadyexisting TDS 'STDS' member.

Step 2:

Run the TP7PREP utility if you are building a new TDS system. Note that because theFlowBus API uses XCP2-CPIC you must specify the XCP2 keyword (i.e XCP2=Y) whenrunning TP7PREP.

If you are using an existing TDS system which was not built with XCP2 you will also haveto run TP7PREP on it.

Step 3:

Run the TP7GEN utility using the 'STDS' member created in step 1.

Step 4:

Modify the Client TPRs NEWAC01 and OPERS01 delivered in the sampleapp library, touse your XCP2 configuration values. The two Cobol move statements which initialize thefields BAB-XCP2-COR and BAB-XCP2-POOL must be updated. For more informationplease see the API reference chapter of this manual.

Step 5:

Compile the forms used by the transaction NEWAC.

Type:

mnform sllib=<dir>.flowbus.sample.sllib binlib=your.binlib; c:compile newac; c:compile confac; c:/

Step 6:

Compile and link, using your compilation and linkage JCLs, the following TPRs deliveredin the sampleapp library:


C-14 86 A2 63CD Rev01

NEWAC01DEPOSITLOCALOPNEWACNOOPENACOPERS01.

Your JCL will need to include the COBOL copy file <dir>.flowbus.copy in the search pathfor the COBOL compiler.

Your JCL will need to include the COBOL compile unit library <dir>.flowbus.culib in thesearch path for the LINKER.

Then, run the 'LINK_TPR' JCL from the delivered library to build the application loaderservice on GCOS 7.

Step 7:

Load the compiled TPRs into backing store using your SYSMAINT JCL.

Step 8:

Run the 'SAMPLEAPP-BLD' JCL from the delivered sampleapp library to prealloc thefiles used by the sample application. You should refer to the JCL for the required valuesto be supplied to this job.

Step 9:

Add the file assignments for the sampleapp files to your TDS run time JCL. Thenecessary file assignments can be found in the example TDS run time JCL 'RUNTDS'delivered in the <dir>.flowbus.sample.sllib library.

Step 10:

Start the TDS system using your run time JCL.


86 A2 63CD Rev01 C-15

C.2.11 How to Run the UNIX components necessary for sampleapp

The following steps should be performed each time you use the sample application.

Step 1:

Type:

. ./setvar


Step 2:

If you want to delete the files which contain information from previous runs of the sampleapplication, type:

rm -f stdout stderr ULOG.*

Step 3:

Type:

tmboot -y

to boot the application.

Step 4:

The XCP2 sessions can now be opened between your UNIX machine and the TDSsystem. For more information on configuring XCP2 for UNIX and GCOS 7 please refer tothe FlowBus System Administration and Configuration Guide.

Step 5:

Now logon to your GCOS 7 system and follow the steps described in the paragraph "Howto run sampleapp on GCOS 7".

Step 6:

The application may be shut down by typing:

tmshutdown -y


C-16 86 A2 63CD Rev01

C.2.12 How to Run sampleapp on GCOS 7

Step 1:

Logon to the TDS system.

Step 2:

Run the account creation transaction by typing:

NEWAC

NEWAC prompts you with a data entry form in which to enter the customer details andthe amount of the first deposit to be made. Use <tab> to move to the next field, <shift-tab> to move to the previous field and <return> to create the savings account.

If the account creation was successful you are presented with another form, whichconfirms the account has been created and displays the account number. If, for anyreason, the account cannot be opened, you will receive an error message on yourterminal. The TUXEDO userlog may also contain useful information for determining thereason for the failure.

Type <return> at the second form to return to the first. To exit NEWAC either type <F1>or, with a empty data entry form, type <return>.When an account is created it is logged in the file <dir>.LOCLOG.

Step 3:

After successfully creating a new account the application adds account informationmessages to a queue called opersQ . This queue can be emptied by running the centraloperations transaction CENTRLOP.

Type:

CENTRLOP

for each message dequeued by the transaction a log entry is added to the<dir>.CENLOG file.

If all the new accounts are logged in <dir>.LOCLOG and <dir>.CENLOG, the applicationis working correctly.

Step 4:

You can view the results of the run by printing the log files using the IOF commands:

s:prf <dir>.cenlog; s:prf <dir>.loclog; s:prf <dir>.saccount; s:prf <dir>.account;

Cenlog and loclog files must have been closed previously (CLOSE_TDS_FILEcommand), or TDS must have been stopped to be printed. These files must be re-opened to continue.


86 A2 63CD Rev01 C-17

C.2.13 How to Delete sampleapp on UNIX

The following steps explain how to delete sampleapp .

Step 1:

In your sampleapp directory, type:

. ./setvar


Step 2:

Remove the IPC resources used for the queue space by typing:

rmqipc

Step 3:

In your sampleapp directory, type:

make clean

to return the sampleapp directory structure to its pre-built state.


C-18 86 A2 63CD Rev01

86 A2 63CD Rev01 g-1

Glossary

The following terms have a special or technical meaning in this manual:

Abort

The process that completes a transaction unsuccessfully. Processing returns to thestate at which the transaction started. See also commit .

API

Application Programmer's Interface. A set of calls and associated usage guidelines foraccessing the functions of FlowBus. Application programmers use the API to createapplication interfaces.

Application

A set of procedures, programs and processes that together provide a set of relatedsystem services associated with a single functional objective. An application isidentified as a single unit for the purpose of integration into FlowBus.

Application Bus

A system that allows applications to communicate in a way analogous to that in whicha LAN allows microcomputers to communicate.

Application Description

A description of an application in terms of characteristics such as its Delivery P ointsand their types.

Application Instance

An executing (or executable) instance of an Application Profile .


g-2 86 A2 63CD Rev01

Application Profile

A description of an application in terms of characteristics such as its Delivery P ointsand their types.

Application Type

An indication as to whether an Application Profile is a user application, a queue or amessage transformation.

Asynchronous Call

A call to a service. The calling application continues processing until a reply isreturned.

ASYNCHRONOUS Instance

In Local Queuing context, an executing (or executable) instance of an ApplicationProfile which uses connections to an LQ instance through local PUT and/or GETdelivery points.

Call

Put a message onto FlowBus and get a reply at the same delivery point. This verbapplies to client applications. See also put , get and serve .

Client

In a client-server transaction processing system, clients are processes that initiatetransactions and call up services by making remote procedure calls.

Commit

The process that completes a transaction successfully. See also abort .

Delivery Point

An application attribute that describes a model of communication with FlowBus.

Get

Receive a message from FlowBus. This verb applies to applications. See also put ,call and serve .

Glossary

86 A2 63CD Rev01 g-3

Invocation

The act of starting an application, including loading and execution, possibly precededby linkage.

JOR

Job Output Report produced after the execution of a job on GCOS 7 system.

LQ Instance

Reliable relay between application instances; configured in network model as otherFlowBus specific application instances like queues or transformers. Must observenaming rules (__ GC7..., __ GC8..., __ MVS... .).

Message

The unit of data exchanged between applications on FlowBus.

Message Base Type

A classification of a message that indicates its format. The base type of a message isused to route it and to transform it as required.

Message Sub-type

A sub-type of a particular message base type, specified by imposing a condition onthe value of one or more fields in the message. A message of a particular sub-typehas the same message format as the parent base type.

MIXED Instance

In Local Queuing context, an executing (or executable) instance of an ApplicationProfile which uses connections to an LQ instance through a local PUT and/or GETdelivery points, and a connection to a non LQ instance through a CALL delivery point.

Put

Pass a message to FlowBus. This verb applies to applications. See also call , get andserve .

Serve

Get a message from FlowBus and put a reply at the same delivery point. This verbapplies to server applications. See also call , get , and put .


g-4 86 A2 63CD Rev01

Server

n a client-server transaction processing system, servers are processes that provideransactional services that may be invoked by remote procedure calls from clients.

STDS

GCOS 7 source Library member containing the TDS generation statements.

Synchronous Call

A call to a service. The calling application stops processing until a reply is returned.

TDS

Transaction Driven System under GCOS 7.

Transaction

A unit of work that either wholly succeeds or has no effect whatsoever. See alsocommit and abort .

Wrapper

Software that envelopes a system component or application to adapt its interface, itsfunctionality, or both, for use on FlowBus.

86 A2 63CD Rev01 i-1

Index

A

ABCALLcoding high-level processes 3-5

Applicationdefinition 1-3

Application bus configuration 1-5examples C-2

Application profilefor application instance B-3generated file 1-6

Applicationsdevelopment route 1-2

B

Build clients iv, 6-1Build servers iv, 6-1

C

CALL 2-3CALL/SERVE delivery point 1-5

coding with ABACALL andABGETRPLY 3-5coding with ABCALL 3-5

Client 1-3Client applications

complex interactions 3-3identifying in design 1-2simple interactions 2-1

Client delivery point 1-5Clients

building iv, 6-1Complex interactions

on client applications 3-3on server applications 3-6

Configurationexamples C-2

COPY filesupplied with FlowBus API A-2

D

Data typesused in FlowBus API A-2

Delivery points 1-5identifying in design 1-2on client applications 2-1, 2-4

E

Error codes 1-7

F

FlowBus API commandsdata types used A-2

Format of messagesidentifying in design 1-2

Formatsof messages 1-6

G

GETon a client applications 2-2on a server 2-5

GET delivery point 1-5coding with ABCALL 3-5

I

Illustrationsof example network models C-2


i-2 86 A2 63CD Rev01

L

Linkapplicaitions iv, 6-1

M

Message base types 1-6Message Classification

Skeleton code 5-3Message classification iv, 5-1Message exchanges

identifying in design 1-2

N

Network modelsexamples C-2

New applications 1-2

P

Processingidentifying in design 1-2

PUTon a client application 2-2on a server 2-4

PUT delivery point 1-5coding with ABCALL 3-5

R

Return codes 1-7

S

SERVE 2-7Server 1-3Server applications

complex interactions 3-6identifying in design 1-2simple interactions 2-4

Server delivery point 1-5Servers

building iv, 6-1Services

in error and return codes 1-7Skeleton code

message classification 5-3

T

TUXEDOerror and return codes 1-7FlowBus API transactional commandsequivalent to iv, 4-1

W

Wrapper 1-2, 1-3

X

X/OPEN XATMIinterface standard 3-2

XATMIinterface standard 3-2

XATMI interface standardtransactional commands iv, 4-1

Technical publication remarks form

Title : DPS7000/XTA NOVASCALE 7000 FlowBusGCOS 7 COBOL Programmer's Guide Distributed Computing

Reference Nº : 86 A2 63CD 01 Date: June 1997

ERRORS IN PUBLICATION

SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION

Your comments will be promptly investigated by qualified technical personnel and action will be taken as required.If you require a written reply, please include your complete mailing address below.

NAME : Date :

COMPANY :

ADDRESS :

Please give this technical publication remarks form to your BULL representative or mail to:

Bull - Documentation Dept.

1 Rue de ProvenceBP 20838432 ECHIROLLES [email protected]

Technical publications ordering form

To order additional publications, please fill in a copy of this form and send it via mail to:

BULL CEDOC357 AVENUE PATTONB.P.2084549008 ANGERS CEDEX 01FRANCE

Phone: +33 (0) 2 41 73 72 66FAX: +33 (0) 2 41 73 70 66E-Mail: [email protected]

CEDOC Reference # Designation Qty

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

[ _ _ ] : The latest revision will be provided if no revision number is given.

NAME: Date:

COMPANY:

ADDRESS:

PHONE: FAX:

E-MAIL:

For Bull Subsidiaries:

Identification:

For Bull Affiliated Customers:

Customer Code:

For Bull Internal Customers:

Budgetary Section:

For Others: Please ask your Bull representative.

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

86 A2 63CD 01REFERENCE

flowbus gcos 7 cobol - bull on-line support...

Documents