VCOM for OS/390 Programmers Manual Version 3.2.

1
Document Number: VM-5105-321

Copyright 2000 NetSys Software Group AB

VM-5105-321 First Edition (March 2000) This edition applies to Version 3 Release 2 Modification Level 1 of VCOM for OS/390. NetSys Software Group AB S-431 85 Mlndal Sweden Tel +46 31-720 60 00 Fax +46 31-27 50 10

Preface
This manual describes methods used with VCOM and specific language and environment dependencies.

Organization of this manual

Chapter 1: contains an introduction to the VCOM system. Chapter 2: contains a description of various methods used. Chapter 3: contains a description of languages supported for a specific environment and how the VCOM verbs are coded in that language. Chapter 4: contains a description of the programming environment. Chapter 5: contains a summary of common problems and trouble shooting. Appendix A: contains a number of programming examples.

Related publications
VCOM API Manual: describes the VCOM Application Programming Interface. VM-5102 VCOM for OS/390 Reference Manual describes how a VCOM for OS/390 system is installed and customized for installation needs. VM-5104 VCOM for OS/390 Operator Manual: describes the VCOM for OS/390 operator function and the commands used for the VCOM for OS/390 system. VM-5103 VCOM for OS/390 Message Manual: contains messages and information codes generated by the VCOM for OS/390 system.

Preface

VCOMPGM

Contents
1.0 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 11 11 12 13 14 14 15 16 19 20 21 22 22 22 22 22 23 23 23 24 24 25 26 27 28 29 29 30 31 32 32 33 33 35 35 35 36 36 36 40 41 41 41 46 46 2.0 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Distribution services . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 Fetch connect parameters . . . . . . . . . . . . . . . . . . . . 2.1.2 Data header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.2.1 Distribution with many records . . . . . . . . . . . . . . 2.1.2.2 Distribution with few records . . . . . . . . . . . . . . . 2.1.3 Sequence of VCOM and DB calls . . . . . . . . . . . . . . 2.1.3.1 Calling sequence . . . . . . . . . . . . . . . . . . . . . . . 2.1.3.2 Two-phase commit . . . . . . . . . . . . . . . . . . . . . . 2.1.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.5 Printable data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.6 Receipt handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Conversation services . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1.1 Application protocol . . . . . . . . . . . . . . . . . . . . . 2.2.1.2 Half-Duplex Flip-Flop protocol . . . . . . . . . . . . . . 2.2.1.3 Speaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1.4 Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1.5 Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1.6 Transaction types . . . . . . . . . . . . . . . . . . . . . . . 2.2.1.7 Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1.8 More data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.2 Fetch connect parameters . . . . . . . . . . . . . . . . . . . . 2.2.3 Data header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.5 Printable data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.6 Application protocol . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.6.1 Application protocol - Question/Answer protocol 1 2.2.6.2 Application protocol - Question/Answer protocol 2 3.0 Language . . . . . . . . . . . 3.1 Cobol . . . . . . . . . . . . . . . 3.1.1 Parameter passing . . 3.1.2 Copy text . . . . . . . . . 3.1.3 Dynamic subprograms 3.2 Fortran . . . . . . . . . . . . . . 3.2.1 Parameter passing . . 3.2.2 Interface code . . . . . 3.3 C . . . . . . . . . . . . . . . . . . 3.3.1 Parameter passing . . 3.3.2 Include files . . . . . . . 3.3.3 Interface code . . . . . 3.4 REXX . . . . . . . . . . . . . . . 3.4.1 Parameter passing . . 3.4.2 Parameter description 3.4.3 API verb description . 3.4.4 Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

Contents

3.4.5 Initialisation . . . . 3.4.5.1 VCOMINI . . . 3.4.5.2 VCOMFIN . . 3.4.6 CSCONS . . . . . . 3.4.7 CSCONR . . . . . . 3.4.8 CSSEND . . . . . . 3.4.9 CSRECV . . . . . . 3.4.10 CSRLSE . . . . . 3.4.11 DSCONS . . . . . 3.4.12 DSCONR . . . . . 3.4.13 DSSEND . . . . . 3.4.14 DSRECV . . . . . 3.4.15 DSRLSE . . . . . 3.4.16 DSRCNS . . . . . 3.4.17 DSPRLS . . . . . 3.5 Assembler . . . . . . . . 3.5.1 Parameter passing 3.6 Cobol for CICS . . . . . 3.6.1 Parameter passing 3.6.2 Copy text . . . . . . 3.7 IDEAL for CICS . . . . 3.7.1 Parameter passing 3.7.2 Copy text . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

47 47 47 48 50 52 53 55 56 59 61 63 65 67 69 70 70 71 71 72 79 79 80 83 83 84 84 85 86 86 86

4.0 Environment . . . . . . . . 4.1 Operation environment . 4.2 CICS . . . . . . . . . . . . . . 4.2.1 Parallell transactions 4.3 IMS . . . . . . . . . . . . . . . 4.4 Batch . . . . . . . . . . . . . . 4.5 TSO . . . . . . . . . . . . . . . 4.6 Started task . . . . . . . . . 5.0 Common problems

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 .. ... ... .. ... ... ... ... .. ... ... ... ... .. ... ... ... ... .. ... ... ... ... .. ... ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 . 90 . 90 . 95 100 106 112 112 114 116 117 118 118 119 120 121 122 122 125 128 131 134 134 138 142 145

Appendix A. Program examples A.1 Cobol program . . . . . . . . . A.1.1 Conversation initiator . A.1.2 Conversation responder A.1.3 Distribution initiator . . . A.1.4 Distribution responder . A.2 Fortran program . . . . . . . . A.2.1 Conversation initiator . A.2.2 Conversation responder A.2.3 Distribution initiator . . . A.2.4 Distribution responder . A.3 C program . . . . . . . . . . . . A.3.1 Conversation initiator . A.3.2 Conversation responder A.3.3 Distribution initiator . . . A.3.4 Distribution responder . A.4 REXX program . . . . . . . . . A.4.1 Conversation initiator . A.4.2 Conversation responder A.4.3 Distribution initiator . . . A.4.4 Distribution responder . A.5 Assembler program . . . . . . A.5.1 Conversation initiator . A.5.2 Conversation responder A.5.3 Distribution initiator . . . A.5.4 Distribution responder .

VCOMPGM

A.6 A.7

CICS Cobol program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 CICS IDEAL program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Contents

VCOMPGM

List of Illustrations
Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. Distribution methods, fetch connect parameters . Distribution methods, data header . . . . . . . . . . . Distribution with many records . . . . . . . . . . . . . Distribution with few records . . . . . . . . . . . . . . . Distribution methods, sequence of VCOM and DB Call sequence . . . . . . . . . . . . . . . . . . . . . . . . . Program logic for initiating program . . . . . . . . . . Reconnect logic for initiator . . . . . . . . . . . . . . . Program logic for responder . . . . . . . . . . . . . . . Distribution methods, error handling . . . . . . . . . Distribution methods, printable data . . . . . . . . . Distribution methods, receipt handling . . . . . . . . Conversation methods, fetch connect parameters Conversation methods, data header . . . . . . . . . Conversation data layout . . . . . . . . . . . . . . . . . Conversation methods, error handling . . . . . . . . Conversation methods, printable data . . . . . . . . Conversation methods, application protocol . . . . Application protocol, One question . . . . . . . . . . Application protocol, Several questions . . . . . . . Proram for enabling parallell CICS transasction . Coding of IMS/VCOM transaction. . . . . . . . . . . .... .... .... .... calls .... .... .... .... .... .... .... ... .... .... .... .... .... .... .... .... .... . . . . . . . . . . . . . . . . . . . . . 11 12 13 14 14 15 17 17 18 19 20 21 25 26 26 27 28 29 29 30 84 85

List of Illustrations

1.0

Introduction
VCOM is designed to provide a common interface to data communications for application system development. This programming interface is consistent across various computer environments, i.e. IBM mainframes, IBM midrange (AS/400), IBM PC's, DEC machines, UNIX etc. The main purpose of VCOM is to provide services for program-to- program communication for distributed application systems. A distributed application system in this context is a system consisting of at least two programs, co-operating in order to perform a function. Normally, the cooperating programs would be geographically separated, i.e. they would run in different computers or environments. They may, however, also run in the same computer, using VCOM as the tool for data transfer. VCOM provides service to an application program in two areas: communications services addressing services

This manual is intended to help the programmer or system developer to design and write applications using VCOM. The manual is also intended to form a complement to the VCOM API manual.

Introduction

11

12

VCOMPGM

2.0

Methods
This section contains a description of methods used with VCOM. Methods for both VCOM conversations and distributions are discussed. Even though some recommendations are given in this chapter, there may very well be occasions where other methods are wanted, needed or better suited. VCOM will work well in many other ways than the ones described in this section. Many of the subjects described are common for both conversation and distribution services but are discussed separately.

2.1

Distribution services
The following paragraph will discuss various matters concerning the VCOM distribution services (VCOM/DS). VCOM distributions are used to send messages between two applications in an asynchronous way, for more information see the VCOM API manual. The subjects covered are: Connect parameters Data headers Sequence of VCOM and DB calls Error handling Character sets and printable data Receipt handling

2.1.1

Fetch connect parameters

+--------------------------+ ! ! ! fetch connect parameters ! ! ! +--------------------------+

Figure 1.

Distribution methods, fetch connect parameters

Methods

13

It is recommended that the connect parameters are stored in 'application database', parameter library or another suitable place and can be read at connect time. The reason for this is to allow increased flexibility. increase the tuning possibilities (e.g: time-out values).

Values that are suited to be read at connect time are: Partner Expediter Initiator Time out Priority Receipt information Security information Sendertag Maximum receive length

If these values are stored in a database used by many VCOM applications, a key into that table must be defined to be able to identify the parameters to use. The key can for instance be program name or subject etc.

2.1.2

Data header

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! ! +--------------------------+

Figure 2.

Distribution methods, data header

The data sent between the two programs must be understood by both ends . This fact indicates that the layout and structure of the data is important. The data can be formatted in many different ways depending on application needs. One criteria to decide how this should be done is the number of records sent. Another criteria is the kind of information needed to be transmitted together with the data, like application names, message type etc.

14

VCOMPGM

One general recommendation, however, is only to send vital data. VCOM/DS uses variable length records (the record length is specified for each record). If the data sent need to be of a fixed length on both sides, this can easily be handled by the two applications (truncating and padding) but the data can still be sent with a variable length. Using variable length records will reduce transfer time and processing costs.

2.1.2.1

Distribution with many records

First record -----------Subject From appl To appl From program

+------------------------------------------------+ ! ! ! ! ! ! ORDER ! PROST ! AKOS ! VGK010 ! ! ! ! ! ! +------------------------------------------------+

Record type +---------------------------------------------+ ! ! ! ! ! ! ORDER header ! 120034 ! 078820 ! 1994-12-01 ! ! ! ! ! ! +---------------------------------------------+ +------------------------------------------------------+ ! ! ! ! ! ! ! ORDER row ! 001 ! 121678 ! 1200 ! VCOM for MVS ! ! ! ! ! ! ! +------------------------------------------------------+ +------------------------------------------------------+ ! ! ! ! ! ! ! ORDER row ! 002 ! 150622 ! 5000 ! Network monitor ! ! ! ! ! ! ! +------------------------------------------------------+ . . . . .

Figure 3.

Distribution with many records

When there are many records in one distribution logically connected, the recommendation is to group them together. The first record in the distribution would then include control information about subject, application names, program name etc. The following records should to start with a record type if records of different type exist in the distribution.

Methods

15

2.1.2.2

Distribution with few records

Subject

From appl

To appl

From program

Record type

+----------------------------------------------------------------+ ! ! ! ! ! ! ! ! ! ORDER ! PROST ! AKOS ! VGK010 ! ORDER head ! 120034 ! ...! ! ! ! ! ! ! ! ! +----------------------------------------------------------------+ . . .

Figure 4.

Distribution with few records

When a distribution consists of only a few records or only one record it is recommended to hold the control information in every record. This to make the processing easier.

2.1.3

Sequence of VCOM and DB calls

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! ! +--------------------------+

Figure 5.

Distribution methods, sequence of VCOM and DB calls

When the distribution data is used together with database update transactions some important circumstances and conditions should be considered. Actions to take: The amount of data in one distribution ought to be the same as for the database transaction. This makes it possible to rollback the distribution and transaction.

16

VCOMPGM

Commit towards the database should be done before DSRLSE towards VCOM. In case of an error it is possible to make a Roll-Back (delete) of the distribution. If the distribution (application data) is only written to a file, this file should be closed before the DSRLSE verb is issued.

Conditions to consider: When sending a distribution, all information about the distribution is deleted if the application is ended abnormally before DSRLSE or DSPRLSE. When receiving a distribution, the distribution is put back on the distribution queue (retaining its position) if the application is ended abnormally before DSRLSE.

2.1.3.1

Calling sequence
Update database actions and VCOM actions should be synchronized with each other. A transaction start corresponds to the DSCONS/DSCONR verbs in VCOM. Database actions like Update, Insert and Delete correspond to the DSSEND and DSRECV verbs and finally the Commit/Rollback correspond to DSRLSE (normal or rollback).

Database +----------------------+ ! Start transaction ! +----------------------+ +----------------------+ ! Update/Insert/Delete ! +----------------------+ . . . +----------------------+ ! Commit ! +----------------------+

VCOM +----------------------+ ! DSCONS / DSCONR ! +----------------------+ +----------------------+ ! DSSEND / DSRECV ! +----------------------+

+----------------------+ ! DSRLSE normal ! +----------------------+ +----------------------+ ! Rollback ! +----------------------+ +----------------------+ ! DSRLSE Rollback ! +----------------------+

Figure 6.

Call sequence

If a database transaction fails, this should result in a rollback of the distribution i.e deleted if it is the initiating side and put back on the distribution queue on the responding side.

Methods

17

Becouse a DSRLSE 'always' succeeds, but a Commit may fail, the Commit must be done before DSRLSE. In this way it is possible to make a rollback of the distribution.

2.1.3.2

Two-phase commit
In the VCOM architecture it is specified how 'two-phase commit' can be obtained when using VCOM distribution services. To be able to do this, VCOM offers two extra verbs, DSPRLS and DSRCNS. These verbs are optional and should only be used by applications that need 'two-phase commit'. DSPRLS (Distribution Services Prepare to Release) is used to tell VCOM to save the data on disc. This also makes it possible to restart the distribution from that point and that is done with DSRCNS (Distribution Services Re-Connect). Both these verbs may only be used on the initiating side. It is only possible to make ONE DSPRLS for each distribution. The next action after a DSPRLS must be an ordinary release DSRLSE or an abnormal end of the program. This indicates as mentioned before that the data in one distribution should correspond to one database transaction (one commit). The distribution id should always be saved in the application database. The status of the distribution is then known in case of a failure. If the transaction is abnormally ended, the distribution may be reconnected using the DSRCNS verb specifying the distribution id to which it wants to re-connect or a search criteria for distributions that have not been correctly concluded. If the commit is successful, the distribution is ended with DSRLSE normal and if the commit fails the distribution ends with DSRLSE rollback. At the responding side the same type of function may be performed without special verbs. If the transaction ends abnormally the distribution is always put back on the distribution queue (rollback). If the commit fails, the application may end the distribution with DSRLSE rollback to put it back on the queue, or DSRLSE hold to put it into hold for further investigations. And finally, if the commit is successful, the application ends the distribution with DSRLSE normal. Figure Figure 7 on page 17 shows the program logic for an initiating program (the application that sends the distribution).

18

VCOMPGM

Start transaction Call DSCONS (rc,...) Retrieve data to send from the database While (data to send) Call DSSEND (rc,...) Update database Retrieve more data to send Enddo Call DSPRLS (rc,...) Save distribution id COMMIT If (Commit = OK) Call DSRLSE (normal) Else Call DSRLSE (rollback) Endif

Figure 7.

Program logic for initiating program

The following is worth mentioning: The distribution id should be saved in the application database directly after the DSPRLS verb but before the commit. In this way, the distribution id is saved together with the other database updates and the id can then be compared with id's retrieved when using the DSRCNS verb. DSPRLS is made before the commit and with the DSPRLS verb VCOM will save the distribution and wait for the DSRLSE verb. Depending on the outcome of the commit the DSRLSE can be either normal or rollback.

Figure 8 on page 17 shows the re-connect logic that may be used to take care of distributions that have not been correctly concluded.

Call DSRCNS (rc,search criteria,...) While (RC = success) Check if distribution id is in application database If (distribution id found) Call DSRLSE (normal) Else Call DSRLSE (rollback) Endif Call DSRCNS (rc,search criteria,...) Enddo

Figure 8.

Reconnect logic for initiator

DSRCNS is used to re-connect to any distribution that is in status 'Prepared to release' and that matches the search criteria specified. The verb can be used by the initiating program itself or it is possible to develop a general supervising program. Whether to include the re-connect logic in the initiating program or to implement a supervising program depends upon a number of factors. The following need to be considered:

Methods

19

Performance of the initiating program. Sequence control. Supervising strategy.

If the distribution id is found in the application database, this indicates that the database was updated and that the distribution should be released (normal). If the distribution id is not found this indicates that the database was not updated and that the distribution should be deleted (rollback).

Figure 9 on page 18 shows the logic for a responding program.

Call DSCONR (rc,...) While (RC = success) Start transaction Check if the distribution id exists in application database If (distribution id found) Call DSRLSE (normal) Else Call DSRECV (rc,...) While (RC = success) Update database Call DSRECV (rc,...) Enddo Save distribution id in application database COMMIT If (Commit = OK) Call DSRLSE (normal) Else Call DSRLSE (rollback) Endif Endif Call DSCONR (rc,...) Enddo

Figure 9.

Program logic for responder

When the program starts to receive a distribution (DSCONR), the distribution id is used to look in the application database to see if it already has been processed or not. If the distribution id is found, it is an indication that the following has occurred. The program was interrupted the last time this distribution was processed. The fact that the distribution id exists indicates that the updates in the database have been made. The distribution is in this case already processed and the only thing left is to perform a DSRLSE normal. If the distribution id is not found in the application database, one of the two following events may have occurred. The program was interrupted the last time this distribution was processed. The fact that the distribution id is not found indicates that the database was not updated and that the distribution should be processed again.

20

VCOMPGM

The distribution has not been processed before (this is the normal case).

2.1.4

Error handling

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! ! +--------------------------+

Figure 10.

Distribution methods, error handling

Proper error handling is always important, also when using VCOM. Matters that need to be considered are: What return codes the program should handle. What return codes/events should result in the program performing an EXIT (ends).

VCOM uses return codes with 4 bytes. When using these return codes in the program it is better to use symbolic names instead, supplied in cobol copytexts or C include files etc. It is suggested that these return codes are grouped together. The catagorization below is an example. Category Normal Try again Try later Exit Description Normal return codes that the application should handle (for instance 'No more records'). Return codes that indicate that the the program should try again (for instance different types of time-out's). Return codes indicating that VCOM is not available and an attempt should be done later (for instance 'VCOM not available') Non recoverable errors requiring intervention by VCOM operator or application owner.

This section does not describe the symbolic names for the return codes. Refer to the 'Language chapter' in this manual. Most of the return codes are not very likely to be issued. The most common action after a return code test is of the type 'EXIT'. When these types of return codes occur, the application should exit the VCOM distribution in a way that is agreed for this specific case. The return code and the VCOM identity parameters

Methods

21

(distribution id, partner, expediter etc) should be logged for problem determination purposes. Following symbolic return codes should at least be handled by the application: Return code Success EOF Timeout Not available Security error Description Ok (Normal) No more records (Normal) Timeout for DSCONS or DSCONR (Try again) VCOM not available (Try later) Security data error (Exit)

2.1.5

Printable data

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! ! +--------------------------+

Figure 11.

Distribution methods, printable data

VCOM can do character translation on request. VCOM can only translate characters that are represented in ISO 8859-1 (ISO-latin-1) and the character sets used by the applications. A translation error occurs when a character does not exist in both user character sets and in ISO 8859-1. For this reason the recommendation is only to use 'printable data' when transferring text that should be understood by both programs. VCOM also has the ability to transfer data as binary. No translation is then performed by VCOM. Note: It is not possible to mix binary and translation mode within one distribution.

2.1.6

Receipt handling

22

VCOMPGM

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! +--------------------------+ +-! ! ! receipt handling ! ! ! +--------------------------+

Figure 12.

Distribution methods, receipt handling

When using VCOM distribution services, the data is always transferred to the other application if no timeout value for the distribution has been specified. This is usually insufficient for as verification that the data has been delivered and that the result was correct. In some cases (when it is necessary), the application developers need to decide how the result of the distribution ought to be verified. In VCOM, this can be accomplished in several ways: Use VCOM receipt handling. Send a ordinary distribution as verification. Use sequence number in the distributions so that later distributions can verify previous distributions. ...

A decision also has to be made whether there always should be some kind of verification or only when an error has occurred.

2.2

Conversation services
This section will discuss various matters concerning the VCOM conversation services (VCOM/CS). VCOM conversations are used to send messages between two applications in a synchronous way, for more information see the VCOM API manual. The subjects covered are: Definitions Connect parameters

Methods

23

Data headers Error handling Character sets and printable data Application protocol

2.2.1

Definitions
When using VCOM/CS, the terminology may need to be expanded. One of the advantages with VCOM is that it uses a common terminology across the different computer platforms. The definitions made here are not included in the VCOM specification but, a terminology like this is needed.

2.2.1.1

Application protocol
A set of rules, which define the data flow and what kind of processing is expected between two connected application programs.

2.2.1.2

Half-Duplex Flip-Flop protocol

Programs using VCOM conversation services exchange data using a Half-Duplex Flip-Flop protocol. Basically this means that only one application at a time can send data.

2.2.1.3

Speaker
The program with has the authority to speak (CSSEND) is the current speaker. The speaker/listener role can be alternated during the connection according to the application protocol. The programs cannot have the same role at the same time. The initiator program is normally the first speaker but does not have to be. This is defined in the application protocol.

2.2.1.4

Listener
The program without the authority to speak (CSSEND) is the current listener (CSRECV). The speaker/listener role can be alternated during the connection according to the application protocol. The programs cannot have the same role at the same time.

2.2.1.5

Transaction
A 'processable' unit transmitted in one direction from current speaker to current listener. The transaction transmission is normally followed by some kind of computer processing by the listener. The speaker/listener

24

VCOMPGM

role is normally alternated after the transmission of a transaction (half duplex flip/flop). Transactions are divided into initiator transactions and response transactions according to the origin (initiator/responder). A transaction should be identified by a transaction id and the same id should be used also for the response and propagated in a (multi)conversation. A transaction can consist of one or more records defined according to the application processing and reply requirements.

2.2.1.6

Transaction types
Within an application area, the following transaction types can be seen as examples depending on the kind of service requested (or demanded). Lock: A request from the current speaker to lock a database entry for later update. A Lock transaction should always be responded to by a Confirm or Reject transaction. A typical example would be to lock an Order entry in a remote data base with the intention to make an update (or Unlock) at a later stage. Unlock: A request from the current speaker to unlock a previous locked data base entry. An Unlock transaction should always be responded toby a Confirm transaction. Request: A Request from the current speaker for remote data base update at the listener site. A Request should always be replied by a Confirm or Reject transaction. An Order Change Request is a typical example. Demand: A Demand from the current speaker for remote database update at the listener site. The Demand transaction should be responded toby a Confirm transaction. No negotiation is possible. The transaction is normally preceded by a confirmed lock. An Order Change Demand (forced update) is a typical example. Query: In this case the current speaker is requesting remote data base retrieve only. The Query transaction should be responded to by a Confirm or Reject transaction depending on the result. Confirm: Normal response to a Lock, Unlock, Request, Demand or Query transaction. Reject Abnormal response to a Lock, Request, Demand or Query transaction. Error: An error transaction is a request from the current speaker for an immediate shut down and can occur at any time within another transaction (More Data = NO, see More data on page 24) or as an own transaction. The main reason for introducing the error transaction is to give a possibility to inform the other side that the protocol has been violated. The speaker should perform error handling procedures, abort the transaction
Methods 25

in progress and disconnect when an error transaction is transmitted. The listener should perform error handling procedures, abort the transaction in progress and disconnect. The Error transaction should be used when possible (instead of merely disconnecting the conversation) in order for both parts to be able to control disconnection. A disconnect (CSRLSE) will cause an unexpected end of data or time out to occur if not preceded by an Error transaction. The Error transaction should not be used for unexpected VCOM return codes. The error transaction should contain a reason code and an error code. Reason code examples: Protocol violation Internal system error

Protocol violation error codes examples: Invalid record length Maximum number of records exceeded Invalid record type Invalid record data

2.2.1.7

Record
A 'protocol unit' included in a transaction. Records normally have some kind of structure and sort order within a transaction. The maximum number of records within a transaction needs to be specified in order to prevent application program buffer overflow from occuring.

2.2.1.8

More data
A means to control the record flow from speaker to listener and indicate the end of the transaction to the listener. The field should be included as a standard item in each record. More data equals YES indicate that there are more records to be received. More data equals NO means that this was the last record in the transaction. When last record is sent/received the speaker/listener role is alternated.

26

VCOMPGM

2.2.2

Fetch connect parameters

+--------------------------+ ! ! ! fetch connect parameters ! ! ! +--------------------------+

Figure 13.

Conversation methods, fetch connect parameters

It is recommended that the connect parameters are stored in an 'application database', parameter library or another suitable place and can be read at connect time. The reason for this is to increase flexibility. increase the tuning possibilities (ex: time-out values).

Values that are suited to be read at connect time are: Partner Expediter Initiator Time out Security information Sendertag Maximum receive length

If these values are stored in a database that are used by many VCOM applications, a key into that table must be defined to be able to identify the parameters to use. The key can for instance be program name or subject etc.

Methods

27

2.2.3

Data header

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! ! +--------------------------+

Figure 14.

Conversation methods, data header

The data that is sent between the two programs must be understood by both ends. This fact indicates that the layout and structure of the data is important. There are several ways to design the structure of the data, but it is important (for performance reasons) to keep the number of CSSEND/CSRECV requests as few as possible. Both network overhead and computer processing time/costs will be reduced if the number of interactions are reduced to a minimum.

Transaction type ! ! More data indicator ! ! ! ! Subject From To From Record ! ! appl appl program type ! ! +-------------------------------------------------------------------+ ! ! ! ! ! ! ! ! ! ! !T!I! ORDER ! PROST ! AKOS ! VGK010 ! ORDER head ! 120034 ! ...! ! ! ! ! ! ! ! ! ! ! +-------------------------------------------------------------------+

Figure 15.

Conversation data layout

28

VCOMPGM

2.2.4

Error handling

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! ! +--------------------------+

Figure 16.

Conversation methods, error handling

Proper error handling is always important and is so also when using VCOM. Matters that need to be considered are: What return codes the program should handle. What return codes/events should result in the program performing an EXIT (ends).

VCOM uses return codes with 4 bytes. When using these return codes in the program it is better to use symbolic names, supplied in cobol copytexts or C include files. It is suggested that these return codes are grouped together. The catagorisation below is an example. Category Normal Try again Try later Exit Description Normal return codes that the application should handle (for instance CSRLSE). Return codes that indicate that the the program should try again (for instance different types of time-out's). Return codes indicating that VCOM is not available and an attempt should be done later (for instance 'VCOM not available') Non recoverable errors requiring intervention by VCOM operator or application owner.

This section does not describe the symbolic names for the return codes. Refer to the 'Language chapter' in this manual. Most of the return codes are not very likely to be issued. The most common action after a return code test is of the type 'EXIT'. When these types of return codes occur, the application should exit the VCOM conversation in a way that is agreed for this specific case. The return code and the VCOM identity parameters (distribution id, partner, expediter etc) should be logged for problem determination purposes. Following symbolic return codes should at least be handled by the application: Return code Success CSRLSE Description Ok (Normal) CSRLSE received (Normal)

Methods

29

Timeout Not availible Security error

Timeout for DSCONS or DSCONR (Try again) VCOM not availible (Try later) Security data error (Exit)

2.2.5

Printable data

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! ! +--------------------------+

Figure 17.

Conversation methods, printable data

VCOM can do character translation upon request. VCOM can only translate characters that are represented in ISO 8859-1 (ISO-latin-1) and the charactersets used by the applications. If a character does not exist in both user charactersets or in ISO 8859-1, a translation error will occur. For this reason the recommendation is only to use 'printable data' when transferring text that should be understood by both programs. VCOM also has the possibility to transfer data as binary, in which case VCOM does not perform any translation. Note: It is not possible to mix binary and translation mode within one conversation.

30

VCOMPGM

2.2.6

Application protocol

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! +--------------------------+ +-! ! ! application protocol ! ! ! +--------------------------+

Figure 18.

Conversation methods, application protocol

The application protocol set up between a pair of application programs control the dataflow, specifies the data layout that is sent and what to do in error situations. This section, however, will only describe the data flow. Transaction types and error handling is described earlier in this chapter. The protocols described here are of the type 'question/answer'.

2.2.6.1

Application protocol - Question/Answer protocol 1

This type of protocol is used when there is always only one question within each conversation. The question can result in several answers. In Figure 19 on page 29, the logic may be seen from the initiating program's point of view. This protocol is for example suitable when the responding program is an IMS or CICS transaction.

Connect

(CSCONS) (CSSEND)

Send Question

loop until no more data to receive Receive Answer end loop Disconnect (CSRLSE) (CSRECV)

Figure 19.

Application protocol, One question

Methods

31

2.2.6.2

Application protocol - Question/Answer protocol 2

This type of protocol is used when the conversation can include several questions. Each question can result in several answers. In Figure 20 on page 30, the logic may be seen from the initiating program's point of view. This protocol is for example suitable when the responding program is a monitor that can handle infinite conversations or if a another process is started for each conversation.

Connect

(CSCONS) (CSSEND)

Send Question

loop until no more questions loop until no more data to receive Receive Answer end loop Send Question end loop Send End mark Disconnect (CSSEND) (CSSEND) (CSRECV)

(CSRLSE)

Figure 20.

Application protocol, Several questions

32

VCOMPGM

3.0

Language
This section describes of how the VCOM verbs are coded for a specific language. In VCOM for OS/390 the following languages are supported: Cobol Fortran C REXX Assembler Cobol for CICS Ideal for CICS

Other languages may be used if they build the parameter list in the same way as Cobol does.

Language

33

3.1
3.1.1

Cobol
Parameter passing
All calls to VCOM are of the type 'called by reference'. Example:
CALL CSCONS USING VCA-RC VCA-CONVID VCA-SECUR VCA-TIMEOUT VCA-SENDERTAG VCA-PARTNER VCA-INITIATOR

END-CALL

More examples can be found in Appendix A. Program examples on page 89.

34

VCOMPGM

3.1.2

Copy text
The copytext below is delivered with the VCOM software.
********************************************************* * * * GENERAL PARAMETER LIST TO CALL VCOM. * * * *********************************************************

01

* * * * * * * * *

VCOM-AREA. 03 RC PIC S9(4) COMP SYNC VALUE ZERO. *** RETURN CODE SET BY VCOM/API *** 03 CONVID PIC X(34) VALUE SPACE. *** CONVERSATION IDENTIFICATION. *** 03 DISTID PIC X(34) VALUE SPACE. *** DISTRIBUTION IDENTIFICATION. *** 03 SECUR. *** SECURITY INFORMATION, OPTIONAL. *** 05 SECUR-LENGTH PIC S9(4) COMP SYNC VALUE ZERO. 05 SECUR-DATA PIC X(99) VALUE SPACE. 03 TIMEOUT PIC S9(5) COMP SYNC VALUE ZERO. *** TIMEOUT VALUE IN SECONDS. *** 03 SENDERTAG PIC X(20) VALUE SPACE. *** SENDER INFORMATION. *** 03 PARTNER PIC X(8) VALUE ZERO. *** ID OF THE RESPONDING PGM WHEN INITIATOR. *** 03 EXPEDITER PIC X(8) VALUE ZERO. *** ID OF THE RESPONDING PGM WHEN RESPONDER. *** 03 INITIATOR PIC X(8) VALUE ZERO. *** ID OF THE INITIATING PROGRAM. *** 03 LENGTH PIC S9(5) COMP SYNC VALUE ZERO. *** LENGTH OF THE AMOUNT OF DATA. *** 03 MAXLENGTH PIC S9(5) COMP SYNC VALUE +9999. *** MAX LENGTH OF DATA THAT MAY BE RECIEVED. *** 03 ACTLENGTH PIC S9(5) COMP SYNC VALUE ZERO. *** ACTUAL LENGHT, SET BY VCOM. *** 03 PRIO PIC X(1) VALUE SPACE. *** DISTRIBUTION PRIRITY, OPTIONAL. *** 03 RECTYPE PIC X(1) VALUE SPACE. *** RECEPTION TYPE, SET BY VCOM. *** 03 RVALUE PIC S9(4) COMP SYNC VALUE ZERO. *** RETURN VALUE, IN RELEASE REQUEST (DSRLSE). *** 03 DATA PIC X(9999) VALUE SPACE. *** USER DATA AREA. *** 03 RECEIPT. *** RECEIPT INFORMATION. *** 05 RECEIPT-DISTID PIC X(34) VALUE SPACE. 05 RECEIPT-PARTNER PIC X(8) VALUE SPACE. 05 RECEIPT-RC PIC S9(4) COMP VALUE ZERO. 05 RECEIPT-LENGTH PIC S9(4) COMP VALUE ZERO. 05 RECEIPT-DATA PIC X(256) VALUE SPACE.

3.1.3

Dynamic subprograms
It is possible to choose whether the VCOM API should be loaded dynamically or if it should be linked together with the application. A dynamic load of the API is recommended. The following definitions need to be made in the program:

Language

35

01

DYNAMIC-SUBPROGRAMS. 03 CSSEND PIC 03 CSRECV PIC 03 CSRLSE PIC 03 CSCONS PIC 03 CSCONR PIC 03 DSSEND PIC 03 DSRECV PIC 03 DSRLSE PIC 03 DSCONS PIC 03 DSCONR PIC 03 DSRCNS PIC 03 DSPRLS PIC

X(8) X(8) X(8) X(8) X(8) X(8) X(8) X(8) X(8) X(8) X(8) X(8)

VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE

'CSSEND 'CSRECV 'CSRLSE 'CSCONS 'CSCONR 'DSSEND 'DSRECV 'DSRLSE 'DSCONS 'DSCONR 'DSRCNS 'DSPRLS

'. '. '. '. '. '. '. '. '. '. '. '.

36

VCOMPGM

3.2
3.2.1

Fortran
Parameter passing
All calls to VCOM is of the type 'called by reference'. Example:
& Call CSCONS(rc,convid,secur_lth,secur,timeout, sendertag,partner,initiator)

More examples can be found in Appendix A. Program examples on page 89. For two specific parameters a structure is usually passed to VCOM. When writing a VCOM program in Fortran these structures are devided into several simple parameters. The parameters concerned are security and receipt that are devided as follows:
secur receipt => => seclen,secur rcpid,rcppart,rcprc,rcplth,rcpdata

The format of the parameters are described in the VCOM API Manual.

3.2.2

Interface code
To be able to make use of the standard VCOM API module and to be able to load the VCOM API dynamically, the parameter list must be constructed in a certain way. This is done by module called VCOMLFOR that must be linked together with the application itself.

Language

37

3.3
3.3.1

C
Parameter passing
All calls to VCOM is of the type 'called by reference'. Example:
cscons(&rc, &csid, &secur, &tmo, &sndtag, &prt, &init);

More examples can be found in Appendix A. Program examples on page 89.

3.3.2

Include files
The include files below are delivered with the VCOM software.

38

VCOMPGM

/* * * * * * * * * * * * * * * * * * */ #ifndef #define

vcom.h Data structures, constants and function prototypes for the VCOM API. The behavior of this file can be controlled by the following macros: WINDOWS WIN32 CLIENT NO_PROTO If you're building a Windows 3.x client, you must define WINDOWS to get the corrent prototypes. Must be defined if you're building a client under Windows 95 or Windows NT. All clients should define this to hide/show all client specific definitions. If you're using an old K&R compiler, which doesn't support function prototypes, define NO_PROTO.

VCOM_H VCOM_H

/* * Vcom return codes */ #include "rc.h" /* * Machine-independent type definitions */ typedef short VcomInt16; /* 16-bit integer typedef unsigned short VcomUInt16; /* 16-bit unsigned integer #ifdef __osf__ /* DecUnix has 64-bit long typedef int VcomInt32; /* 32-bit integer typedef unsigned int VcomUInt32; /* 32-bit unsigned integer #else typedef long VcomInt32; /* 32-bit integer typedef unsigned long VcomUInt32; /* 32-bit unsigned integer #endif /* CSID - Conversation ID csid { id 34; */

*/ */ */ */ */ */ */

struct char }; typedef /*

struct

csid

CSID; */

DSID - Distribution ID dsid { id 34;

struct char }; typedef

struct

dsid

DSID;

Language

39

/*

Structure to describe security info in connect calls

*/

struct secinfo { VcomInt16 usdlen; char usdata 99; }; typedef struct secinfo SECINFO;

/*

Structure used to describe a receipt in DSCONS calls

*/

struct receipt { char dsid 34; /* Original distid */ char partner 8; /* Receiving partner */ short rc; /* Return code: /* <= 0 -- receipt on error */ /* > 0 -- receipt always */ VcomInt16 len; /* Length of receipt data */ /* User data (if any) comes here */ }; typedef struct receipt RECEIPT;

*/

/*

Prototype declarations of the VCOM API functions

*/

#if defined(WINDOWS) #define _zvfundecl far pascal _export #elif defined (WIN32) #define _zvfundecl __stdcall #else #define _zvfundecl #endif #ifndef NO_PROTO #if defined(__cplusplus) extern "C" { #endif

40

VCOMPGM

extern void _zvfundecl cscons(VcomInt16 *retcode, CSID *csid, SECINFO *secinfo, VcomInt32 *timeout, char *sendertag, char *partner, char *initiator); extern void _zvfundecl csconr(VcomInt16 *retcode, CSID *csid, SECINFO *secinfo, VcomInt32 *timeout, char *sendertag, char *expediter, char *initiator); extern void _zvfundecl cssend(VcomInt16 *retcode, CSID *csid, VcomInt32 *length, void *data); extern void _zvfundecl csrecv(VcomInt16 *retcode, CSID *csid, VcomInt32 *timeout, VcomInt32 *maxlength, VcomInt32 *actlength, void *data); extern void _zvfundecl csrlse(VcomInt16 *retcode, CSID *csid); #ifdef CLIENT extern void _zvfundecl consrv(VcomInt16 *rc, char *server); extern void _zvfundecl discsrv(VcomInt16 *rc, char *server); extern VcomInt16 _zvfundecl dmpvcom(char *fileName); extern void _zvfundecl getvcomver(char **version); #endif extern void _zvfundecl dscons(VcomInt16 *retcode, DSID *dsid, SECINFO *secinfo, VcomInt32 *timeout, char *sendertag, char *partner, RECEIPT *receipt, char *prio, char *initiator); extern void _zvfundecl dsconr(VcomInt16 *retcode, DSID *dsid, SECINFO *secinfo, VcomInt32 *timeout, char *sendertag, char *expediter, char *rectype, char *initiator); extern void _zvfundecl dssend(VcomInt16 *retcode, DSID *dsid, VcomInt32 *length, void *data); extern void _zvfundecl dsrecv(VcomInt16 *retcode, DSID *dsid, VcomInt32 *maxlength, VcomInt32 *actlength, void *data); extern void _zvfundecl dsrlse(VcomInt16 *retcode, DSID *dsid, VcomInt16 *rvalue); extern void _zvfundecl dsrcns(VcomInt16 *retcode, DSID *dsid, SECINFO *secinfo, char *partner, char *initiator); extern void _zvfundecl dsprls(VcomInt16 *retcode, DSID *dsid); #ifndef CLIENT extern void _zvfundecl opercon(VcomInt16 *retcode, CSID *csid, VcomInt32 *timeout, char *network, char *node, char *initiator); extern void _zvfundecl opercmd(VcomInt16 *retcode, CSID *csid, VcomInt32 *timeout, VcomInt32 *clength, VcomInt32 *rmax, VcomInt32 *rlength, char *command, char *response); extern void _zvfundecl operrls(VcomInt16 *retcode, CSID *csid); #endif #if defined(__cplusplus) } #endif #else /* NO_PROTO */

Language

41

extern extern extern extern extern #ifdef extern extern extern extern #endif extern extern extern extern extern extern extern

void void void void void

cscons(); csconr(); cssend(); csrecv(); csrlse();

CLIENT void void VcomInt16 void

_zvfundecl _zvfundecl _zvfundecl _zvfundecl

consrv(); discsrv(); dmpvcom(); getvcomver();

void void void void void void void

dscons(); dsconr(); dssend(); dsrecv(); dsrlse(); dsrcns(); dsprls();

#ifndef CLIENT extern void _zvfundecl extern void _zvfundecl extern void _zvfundecl #endif #endif #endif /* NO_PROTO */ /* VCOM_H */

opercon(); opercmd(); operrls();

/* * * * * */

rc.h VCOM return codes

#define VCOM_RC_SUCCESS #define #define #define #define

/* Universal success code /* /* /* /* Normal release Rewind a distribution Synonym to _REWIND_DS Hold a distribution

*/ */ */ */ */

VCOM_RC_NORMAL 1 VCOM_RC_REWIND_DS -1 VCOM_RC_ROLLBACK -1 VCOM_RC_HOLD_DS -2

#define VCOM_RC_RLSE_SESS 35 #define VCOM_RC_NODISTR 41 #define VCOM_RC_DB_EOF 45

/* Counterpart released session */ /* No distribution found */ /* End of file */

3.3.3

Interface code
To be able to make use of the standard VCOM API module and to be able to load the VCOM API dynamically, the parameter list must be constructed in a certain way. This is done by a very small module called VCOMLC that must be linked together with the application itself.

42

VCOMPGM

3.4

REXX
The REXX programming language differs in several ways from other programming languages such as Cobol. A special VCOM REXX api has therefore been developed to define an easy and very REXX like way to use the VCOM verbs from the REXX language. The idea is that this interface should give the REXX programmer a way to use VCOM following the REXX calling conventions. This means that the developer should not need to do any extra coding around the VCOM verbs when using them.

3.4.1

Parameter passing
The arguments passed in the REXX verbs are only of type input. The data passed is always the data, not addresses or pointers. Output arguments are returned in standard output variables. These variables are defined after a call to VCOM has been performed. The output variable names are built from a prefix concatenated with a specific output parameter name. For an omitted parameter the following rules applies: 1 2 Pass a comma with no previous argument to indicate that you are not passing an argument. You can also pass a string containing no characters at all.

3.4.2

Parameter description
The following table describes the parameters used together with the VCOM API verbs.

Name prefix

Type <= 20 characters

Description Prefix name, prefixes output parameter names. If the prefix is longer than 20 characters it will be truncated with no warning. Return code. Value set by VCOM after a verb has completed.

rc

>= 1 char

Language

43

Name convid distid

Type 34 characters

Description Session id for a conversation or a distribution. The conversation id or distribution id is assigned by VCOM after a connection has been established. The id is 34 characters and has the following structure: net node crtim seqnr VCOM network name of initiator (8 characters). VCOM node name of initiator (8 characters). session id time stamp in the format YYYYMMDDhhmmss (14 characters). session id sequence number (4 characters).

secur

0..99 characters

Security information. The parameter can be used to exchange security information. If the parameter is used, both the initiator and the responder must specify the same information in order to have a connection established. The parameter must either be specified by both sides or be omitted by both sides. The security information can be up to 99 characters long. Note that this parameter is translated by VCOM into the character code appropriate for the environment where the VCOM implementation is run. The valid character set to use is VCOM character set.

timeout

1..8 characters

Timeout value. The timeout value is specified in seconds and the maximum value that may be used is 365 days (corresponding to a value of 31.536.000 seconds). Text string. The sendertag is any string that the sender wishes to send to the receiver in the connect phase. Note that this parameter is translated by VCOM into the character code appropriate for the environment where the VCOM implementation is run. The valid character set to use is VCOM character set.

sendertag

0..20 characters

partner

1..8 characters

Partner identification. This is the identification given by an initiator to indicate with whom a conversation is to be established or to whom a distribution is to be sent. Expediter identification. This is the identification given by a responder to inform of the expediter name of the responding process.

expediter

1..8 characters

44

VCOMPGM

Name rectype

Type 1 character

Description Receive type. The receive type identifies the type of distribution that is going to be received by a distribution responder. One of the following values are used: D Data. Used to indicate a normal data distribution. R Receipt. Used to indicate a receipt distribution.

receipt

character string

Receipt information. The receipt information is specified by the originator of a distribution when the distribution is created. The receipt information has the following structure: distid partner rc length data id of the original distribution associated with the receipt. the partner name of the recipient. return code for the distribution associated with the receipt. length of receipt data (16 bits). Max length is 256 bytes. user receipt data. This is the receipt data as specified by the originator of the associated distribution when the distribution was created.

prio

1 character

Distribution priority. The priority assigned a distribution by its originator. One of the following values may be used: N normal distribution priority. E express distribution priority.

(c)(r)data

character string

User data area. Area containing user data to send or area into which VCOM will deliver received data. Length of user data area. Length of user data area to send or length of input area to be used for receive. The maximum length is 9999 bytes.

(c)(r)length

>= 0 character

rvalue

>= 1 character

Return value. A return value given by a distribution sender or receiver in a release request (DSRLSE) to indicate the further processing of the distribution by VCOM.

Language

45

Name Initiator

Type 1..8 characters

Description Initiator identification. This is the identification given by the primary side to indicate from whom a conversation request or a distribution request originates.

46

VCOMPGM

The following variables is set by the VCOM REXX api, they are not prefixed by the prefix name, described earlier. Name vcomwork Type 4 characters Description Work code, set by the VCOMINI verb. The code must be passed in all following VCOM verbs.

result

>= 1 Result value (return code). character(s) The result code is set in the calling program if a verb is called as a subroutine. >= 1 Rc, return code. character(s) The return code is set in the calling program if a verb is called as a function.

rc

Language

47

3.4.3

API verb description

The following pages describes each of the verbs provided by the VCOM REXX API. Each verb description also includes the parameters specific to that verb. After each parameter name is specified whether the parameter value is set by the application program or by VCOM. The notation i is used for input parameters set by the application program before the verb is issued. The notation o is used for output parameters set by VCOM after the verb has completed.

3.4.4

Return codes
Return codes are transferred to the REXX environment in several ways, the way it's retuned depends on how the VCOM verb was called from the application. If the VCOM verb was called as a subroutine, the return code is placed in the REXX special variable 'RESULT'. If the VCOM verb was called as a function, the function call is replaced by the return code when returning to the application. There is also a special VCOM variable 'RC', that is set by the api before it returns control to the application. The 'RC' may be prefixed by the prefix parameter.

48

VCOMPGM

3.4.5

Initialisation
Added to the commonly used VCOM verbs are two verbs only used by the REXX api. These verbs are provided to setup and remove an environment used by the REXX api only. Before you are allowed to perform any CS or DS verbs you must do a VCOMINI call. This verb will declare and set a variable called 'vcomwork'. This name must be passed in all verbs following the 'VCOMINI' verb. When you have performed your last CS/DS verb you should release the environment by calling 'VCOMFIN'. Note: VCOMINI should be called only once at the beginning of a VCOM session, VCOMFIN should be called only once at the end of a session.

3.4.5.1

VCOMINI
Verb: Description: VCOMINI () The verb is used to initiate an api session. You are only allowed to perform this call once, before your first CS or DS verb.

The following output parameters are set by the REXX interface. The output names are not prefixed. vcomwork (o) work code. The string is set by VCOM/API at the completion of the verb. The variable is four characters long and contains a binary value. The code is only for internal use, the only thing you can do with it is to pass it to the api.

3.4.5.2

VCOMFIN
Verb: Description: VCOMFIN (vcomwork) The verb is used to terminate an api session. You are only allowed to perform this call once, after your last CS or DS verb.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required.

Language

49

3.4.6

CSCONS
Verb: Description: CSCONS (vcomwork, prefix, secur, timeout, sendertag, partner, initiator) The verb is used to initiate a conversation with a partner.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The maximum length is 20 characters. The parameter is optional. secur (i) security information. A text string has to be given by the application program if a security check is to be made against the partner program. If the parameter is omitted or empty, the specified partner must also use an omitted or empty security information parameter in order for a connection to be established by VCOM. The parameter, if passed, should be a text string. The maximum length of the string is 99 characters. The parameter is optional. timeout (i) timeout value in seconds. The string passed should contain a numeric value. A positive value indicates the maximum time in seconds that the initiator is prepared to wait for the conversation to be established. A negative value may be used to indicate that no timeout value is to be used, i.e. the initiator is prepared to wait indefinitely for the conversation to be established. A value of zero may be used to indicate that the initiator will not wait for a conversation to be established but will only accept a conversation if the conversation responder is immediately available. This is only applicable between two partners in the same node. The parameter is a numeric string of 1 to 8 characters. The parameter is required.

50

VCOMPGM

sendertag (i)

sender information. The parameter is a string of characters that the initiator of the conversation wishes to send to the conversation responder. The maximum length is 20 characters. The parameter is optional.

partner (i)

identification of the partner program. The string is used by the application program to identify the partner process to which a conversation is requested. The parameter is a string of 1 to 8 characters. The parameter is required.

initiator (i)

identification of the initiator program. The parameter is used by the application program to identify the partner process from whom the connect request originates. The parameter is a string of 1 to 8 characters. The parameter is optional.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. The string is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. convid (o) conversation id. This is the identification of the conversation and this id must be used in all subsequent verbs issued to the same conversation. The string is set by VCOM/API at the completion of the verb if the return code indicates that a conversation has been started. The parameter is a string of 34 characters.

Language

51

3.4.7

CSCONR
Verb: Description: CSCONR (vcomwork, prefix, secur, timeout, expediter) The verb is used to respond to a conversation request from a partner program. The verb can also be used by a responder program to connect to VCOM in order to register itself as an expediter even though no conversation requests currently are pending.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. secur (i) security information. A text string has to be given by the application program if a security check is to be made against the partner program. If the parameter is omitted or empty, the specified partner must also use an omitted or empty security information parameter in order for a connection to be established by VCOM. The parameter, if passed, should be a text string. The maximum length of the string is 99 characters. The parameter is optional. timeout (i) timeout value in seconds. The string passed should contain a numeric value. A positive value indicates the maximum time in seconds that the responder is prepared to wait for a conversation to be established. A negative value may be used to indicate that no timeout value is to be used, i.e. the responder is prepared to wait indefinitely for a conversation request from a partner program. A value of zero may be used to indicate that the responder will not wait for a conversation request but will only accept a pending conversation request. The parameter is a numeric string of 1 to 8 characters. The parameter is required.

52

VCOMPGM

expediter (i)

identification of the responding program. This string is used by the application program in order to identify to VCOM the name of the expediter that is starting. The parameter is a string of 1 to 8 characters. The parameter is required.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. convid (o) conversation id. This is the identification of the conversation and this id must be used in all subsequent verbs issued to the same conversation. The variable is set by VCOM/API at the completion of the verb if the return code indicates that a conversation has been started. The parameter is a string of 34 characters. sendertag (o) sender information. This is a variable that will be set to the value given to sendertag by the initiator when the conversation was started. The variable is 0 to 20 characters long information text. initiator (o) identification of the initiator program. The variable is set by the primary application program to identify the partner process from whom the connect request originates. The variable is 0 to 8 character long name.

Language

53

3.4.8

CSSEND
Verb: Description: CSSEND (vcomwork ,prefix, convid, length, data) The verb is used to send data on a conversation to a partner program.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. convid (i) conversation id. This is the identification of the conversation on which the data is to be sent. The parameter is a string of 34 characters. The parameter is required. length (i) length information. The length parameter specifies the amount of data to send. The maximum length differs between the different enviroments. The parameter is optional and the default length is set to the length of the data string. The parameter is a numeric string of maximum 4 characters The parameter is optional. data (i) user data. User data that is to be sent on the conversation to the partner program. The parameter is an alphanumeric string. The parameter is required.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This field is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only.

54

VCOMPGM

3.4.9

CSRECV
Verb: Description: CSRECV (vcomwork, prefix, convid, timeout, maxlength) The verb is used to receive data on a conversation to a partner program.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. convid (i) conversation id. This is the identification of the conversation on which data is to be received. The parameter is a string of 34 characters. The parameter is required. timeout (i) timeout value in seconds. The parameter passed should contain a numeric value. A positive value indicates the maximum time in seconds that the responder is prepared to wait for data to arrive. If no data arrives within this time period, the receive request will be completed with return code VCOM_RC_TIMEOUT. A negative value may be used to indicate that no timeout value is to be used, i.e. the responder is prepared to wait indefinitely for data to arrive. A value of zero may be used to indicate that the responder will not wait for data but will only accept data that is pending on the conversation (i.e. polling). If no data is present on the conversation, the receive request will be completed with return code VCOM_RC_NODATA. The parameter is a numeric string of 1 to 8 characters. The parameter is required. maxlength (i) maximum length. The maximum length parameter specifies the maximum amount of data that may be received in the data area. The parameter is optional and
Language 55

is set to '9999' by default. The maximum length differs between the different environments. The parameter is a numeric string of maximum 4 characters The parameter is optional.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. actlength (o) actual length. The actual length variable is set by VCOM at the completion of the verb and indicates the amount of data received into the data area. The parameter is a numeric string. data (o) user data area. User data area that is used for reception of data on the conversation to a partner program. The variable can contain any form of received data.

56

VCOMPGM

3.4.10

CSRLSE
Verb: Description: CSRLSE (vcomwork, prefix, convid) The verb is used to terminate a conversation to a partner program.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. convid (i) conversation id. This is the identification of the conversation which is to be terminated. The parameter is a string of 34 characters. The parameter is required.

The following output parameter is set by the REXX interface. The output name is prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only.

Language

57

3.4.11

DSCONS
Verb: Description: DSCONS (vcomwork, prefix, secur, timeout, sendertag, partner, receipt, prio, initiator) The verb is used to initiate a distribution to a partner.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. secur (i) security information. The parameter is set by the application program if a security check is to be made against the partner program. If this parameter is omitted or empty, the specified partner must also use an omitted or empty security information parameter in order for a distribution to be delivered by VCOM to the partner. The parameter is a 0 to 99 bytes long alphanumeric string. The parameter is optional. timeout (i) timeout value in seconds. The parameter passed should contain a numeric value. A positive value indicates the maximum time that may flow before the distribution has been delivered to the recipient. A negative value indicates that no timeout is associated with the distribution. The value zero is not used. The parameter is a numeric string of 1 to 8 characters. The parameter is required. sendertag (i) sender information. The parameter contains any string of characters that the sender of the distribution wishes to send to the distribution recipient. The data type is a 1 to 20 character long string. The parameter is optional.

58

VCOMPGM

partner (i)

identification of the partner program. The parameter is set by the application program to identify the partner process to which the distribution shall be delivered. The parameter is 1 to 8 character long name. The parameter is required.

receipt (i)

receipt information. This data structure will be passed to the receipt recipient when a distribution has been delivered to and accepted by its recipient or if timeout occurs. The parameter is a structured string described below. The parameter is optional.

prio (i)

distribution priority. The parameter specifies the requested priority for the distribution. The parameter is a one byte character code. The parameter is optional and if omitted, 'normal' priority will be used by VCOM.

initiator (i)

identification of the initiator program. The parameter is set by the application program to identify the partner process from whom the distribution was delivered. The parameter is 1 to 8 character long name. The parameter is optional.

The receipt information is a structured text string. The string can have a length between 13 and 269 characters depending on user data. The string contains the fields described below in that order. partner (i) identification of the receipt partner program. The field is set by the application program to identify the partner process to which the receipt shall be delivered. The data type is a string of 8 bytes, padded with blanks if the name is shorter than eight characters. rc (i) selection of receipt processing. The field is set by the application program to indicate how VCOM is to handle the receipt processing. The following values may be used: >0 <=0 indicates that the receipt always is to be delivered to the receipt recipient. indicates that the receipt is to be delivered to the receipt recipient if an error or timeout occurs or if the distribution recipient gives a return value of <-999 when the DSRLSE verb is issued.

Language

59

The type is a numeric string of 5 bytes, padded with zeroes if the number is shorter than five characters. data (i) user data. User data to be included in the receipt. The type is an alphanumeric string.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. distid (o) distribution id. This is the identification of the distribution and this id must be used in all subsequent verbs issued to the same distribution. The variable is set by VCOM/API at the completion of the verb if the return code indicates that a distribution has been started. The parameter is a string of 34 characters.

60

VCOMPGM

3.4.12

DSCONR
Verb: Description: DSCONR (vcomwork, prefix, secur, timeout, expediter) The verb is used by an application program to identify itself to VCOM as a distribution receiver.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. secur (i) security information. The parameter is set by the application program if a security check is to be made against the partner program. If this parameter is omitted or empty, the initiating partner must also use an omitted or empty security information string in order for a distribution to be delivered by VCOM to the partner. The parameter is a 0 to 99 characters long alphanumeric string. The parameter is optional. timeout (i) timeout value in seconds. The parameter passed should contain a numeric value. A positive value indicates the maximum time that the responder is prepared to wait for a distribution to arrive. A negative value may be used to indicate that no timeout value is to be used, i.e. the responder is prepared to wait indefinitely for a distribution to arrive. A value of zero may be used to indicate that the responder will not wait for a distribution arrival but will only accept a pending distribution. If no distribution is pending, the request will be completed with the return code VCOM_RC_NODISTR. The parameter is a numeric string of 1 to 8 bytes. The parameter is required. expediter (i) identification of the responding program. This parameter is set by the application program in order to identify to VCOM the name of the expediter that is starting.
Language 61

The parameter is 1 to 8 character long. The parameter is required.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. distid (o) distribution id. This is the identification of the distribution and this id must be used in all subsequent verbs issued to the same distribution. The variable is set by VCOM/API at the completion of the verb if the return code indicates that reception of a distribution has been started. The parameter is 34 character long. rectype (o) reception type. This variable is set by VCOM to indicate the type of distribution to be delivered to the responding program. The type is a character code. initiator (o) identification of the initiator program. The variable is set by the primary application program to identify the partner process from whom the distribution was delivered. The variable is 1 to 8 character long. sendertag (o) sender information. This is an variable that will be set to the value given to sendertag by the initiator when the distribution was started. The value is 0 to 20 character long.

62

VCOMPGM

3.4.13

DSSEND
Verb: Description: DSSEND (vcomwork, prefix, distid, length, data) The verb is used to send data on a distribution to a partner program. Note that the data transfer is a local process between the application program and the local VCOM node.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. distid (i) distribution id. This is the identification of the distribution on which the data is to be sent. The parameter is a string of 34 characters. The parameter is required. length (i) length information. The length parameter specifies the amount of data to send. The maximum length differs between the different environments. The parameter is optional and the length will be set to the length of the data string by default. The parameter is a numeric string of maximum 4 characters. The parameter is optional. data (i) user data. User data that is to be sent on the distribution to the partner program. The data type is a character string. The parameter is required.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb.

Language

63

The variable is four characters long and contains numerics only.

64

VCOMPGM

3.4.14

DSRECV
Verb: Description: DSRECV (vcomwork, prefix, distid, maxlength) The verb is used to receive data in a distribution from a partner program or to receive a receipt distribution. Note that the data transfer is a local process between the application program and the local VCOM node.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. distid (i) distribution id. This is the identification of the distribution on which data is to be received. The parameter is a string of 34 characters. The parameter is required. maxlength (i) maximum length. The maximum length parameter specifies the maximum amount of data that may be received in the data area. If the parameter is omitted the length will be set to '9999'. The maximum length differs between the different environments. The parameter is a numeric string of maximum 4 characters. The parameter is optional.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. actlength (o) actual length. The actual length variable is set by VCOM at the completion of the verb and indicates the amount of data received into the data area.

Language

65

The value is a numeric string. data (o) user data area. User data area that is going to be used for reception of data in the distribution from a partner program. In case of receiving a receipt the data has almost the same structure as when it was given to VCOM and will be received with one DSRECV. The receipt structure can be seen below: distid 34 - characters id of the original distribution associated with the receipt. 8 - characters the partner name of the recipient. 2 - characters NOTE, BINARY VALUE return code for the distribution associated with the receipt. You can convert the binary return code by using the following two REXX instructions. rc_binary = SUBSTRING(data,43,2) rc = C2D(rc_binary,2) length 2 - characters NOTE, BINARY VALUE length of receipt data. You can convert the binary length value by using the following two REXX instructions. length_b = SUBSTRING(data,45,2) length = C2D(length_b,2) data 0 to 256 characters User receipt data. This is the receipt data as specified by the originator of the associated distribution when the distribution was created.

partner rc

The value is a structured string.

66

VCOMPGM

3.4.15

DSRLSE
Verb: Description: DSRLSE (vcomwork, prefix, distid, rvalue) The verb is used to terminate a distribution to a partner program or to terminate the reception of a distribution.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. distid (i) distribution id. This is the identification of the distribution which is to be terminated. The parameter is a string of 34 characters. The parameter is required. rvalue (i) return value. The return value specifies the termination condition when the release verb is issued by a distribution sender. The return value is used by a distribution receiver to specify the return value to use in a receipt defined by the creator of the distribution. As a sender, the following values may be used: 1 indicates normal release of a distribution, i.e. the distribution is to be forwarded by VCOM to its ultimate destination. any other value than 1 indicates that the distribution is to be cancelled.

not 1

As a receiver, the following values may be used: >=0 indicates that the distribution is accepted by the receiver. If a receipt is associated with the distribution, the return code in the receipt will be updated with the rvalue and VCOM receipt processing will begin. To be able to see who is giving the return code (VCOM or the application), it is strongly recom-

Language

67

mended for the application to use 0, 1 or 900-999 to indicate OK. Return codes between 2 and 900 are reserved for VCOM and returncodes with absolute values > 999 indicates error. <-999 indicates that the distribution is accepted by the receiver. If a receipt is associated with the distribution, the return code in the receipt will be updated with the rvalue and VCOM receipt processing will begin. Depending on enviroment the presentation of the receipt-rc, when receiving the receipt, can be either positive or negative why usually the absolute value rather than the signed value should be considered. This range of rvalue can be used to indicate error situations to the receipt handling program, although the distribution is finished as far as VCOM is concerned. -1 indicates that the distribution is rejected and should be returned to VCOM for restart. The next DSCONR will return the same distribution again. indicates that the distribution is rejected and should be returned to VCOM and put in hold status. Normal VCOM receipt processing is started when this value is used.

-2

The parameter is a numeric string. The parameter is required.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only.

68

VCOMPGM

3.4.16

DSRCNS
Verb: Description: DSRCNS (vcomwork, prefix, distid, secur, partner, initiator) The verb is used to re-connect to an interrupted distribution at the primary side. To be able to do re-connect to a distribution a DSPRLS verb must have been issued to that distribution before it was interrupted. The only action that can be done to this distribution is a release (DSRLSE).

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. distid (i) distribution id. This is the identification of the distribution. If a value is given this will be used to find that distribution. The parameter is a string of 34 characters. The parameter is optional. secur (i) security information. The parameter is set by the application program if a security check is to be made against the partner program. If this parameter is omitted or empty, the initiating partner must also use an omitted or empty security information field in order for a distribution to be delivered by VCOM to the partner. The parameter is 0 to 99 character long. The parameter is optional. partner (i) identification of the partner program. The parameter is used to search for distributions matching this partner. The parameter is 1 to 8 character long. The parameter is optional. initiator (i) identification of the initiating program. The parameter is used to search for distributions matching this initiator. The parameter is 1 to 8 character long.

Language

69

The parameter is optional.

The following output parameters are set by the REXX interface. The output names are prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only. distid (o) distribution id. This is the identification of the distribution. If no id was given in the call, this variable will contain a distribution id if one exists that has been interrupted and match the search criteria. The variable is 34 character long.

70

VCOMPGM

3.4.17

DSPRLS
Verb: Description: DSPRLS (vcomwork, prefix, distid) The verb is used to force VCOM to save the data on disk. When this is done the distribution can be restarted if necessary. This verb can only be issued immediately before the DSRLSE verb i.e. the only action that can be made to this distribution is a release (DSRLSE). This verb together with DSRLSE are the only verbs that can be used to make VCOM responsible for that distribution i.e. secure the distribution on disk.

The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter is required. prefix (i) Prefix name. The prefix is used to prefix the standard output names. If the parameter is omitted the default prefix will be 'VCOM'. The parameter, if passed, should be a valid name. The name can contain a maximum of 20 characters. The parameter is optional. distid (i) distribution id. This is the identification of the distribution on which a checkpoint should be taken. The parameter is a string of 34 characters. The parameter is required.

The following output parameter is set by the REXX interface. The output name ise prefixed by the prefix value passed through the verb. rc (o) return code. This variable is set by VCOM/API at the completion of the verb. The variable is four characters long and contains numerics only.

Language

71

3.5
3.5.1

Assembler
Parameter passing
All parameters in VCOM calls are passed 'by reference'. Example:
LOAD LR CALL EP=CSCONS R15,R0 (15),(VCRC,VCSID,VCSECUR, VCTIMOUT,VCSNDTAG,VCPART,VCINIT),VL

More examples can be found in Appendix A. Program examples on page 89.

72

VCOMPGM

3.6
3.6.1

Cobol for CICS

Parameter passing
All calls to VCOM are executed using the LINK function. This means that it is not possible to supply a parameter list when using the VCOM verbs. Instaed an area is passed that contains the parameters needed. Example:
MOVE LENGTH OF CSCONS TO W-LENGTH EXEC CICS LINK PROGRAM('CSCONS') COMMAREA(CSCONS) LENGTH(W-LENGTH) END-EXEC

More examples can be found in Appendix A. Program examples on page 89.

Language

73

3.6.2

Copy text
The copytexts below are delivered with the VCOM software. There are two types of copy texts delivered. One type uses a tag function, which means that the tag will be replaced when the program is compiled using the following statement:
COPY CCSCONS REPLACING ==:TAG:== BY ==CSCONS==

The other type uses a pre-processor to add a prefix on all the parameters. Example:
-COPY CVCSCONS -PRE CSCONS-

The naming conventions for the two different types are:

Cxxxxxx CVxxxxxx where xxxxxx is the VCOM verbs when using :TAG: where xxxxxx is the VCOM verbs when using the preprocessor

CCSCONS 01 :TAG:. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-SECUR. 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT 05 :TAG:-SENDERTAG 05 :TAG:-PARTNER 05 :TAG:-INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(8)

VALUE VALUE VALUE VALUE

ZERO. SPACE. SPACE. SPACE.

CVCSCONS 01 CSCONS. 05 RC 05 CONVID 05 SECUR. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 PARTNER 05 INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(8)

VALUE VALUE VALUE VALUE

ZERO. SPACE. SPACE. SPACE.

74

VCOMPGM

CCSCONR 01 :TAG:. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-SECUR. 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT 05 :TAG:-SENDERTAG 05 :TAG:-EXPEDITER 05 :TAG:-INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(8)

VALUE VALUE VALUE VALUE

ZERO. SPACE. SPACE. SPACE.

CVCSCONR 01 CSCONR. 05 RC 05 CONVID 05 SECUR. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 EXPEDITER 05 INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(8)

VALUE VALUE VALUE VALUE

ZERO. SPACE. SPACE. SPACE.

CCSSEND 01 :TAG:. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-LENGTH 05 :TAG:-DATA

COMP PIC PIC COMP PIC PIC

S9(4). X(34) VALUE SPACE. S9(8) VALUE ZERO. X(9999).

CVCSSEND 01 CSSEND. 05 RC 05 CONVID 05 LENGTH 05 DATA

COMP PIC PIC COMP PIC PIC

S9(4). X(34). VALUE SPACE. S9(8). VALUE ZERO. X(9999).

Language

75

CCSRECV 01 :TAG:. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-TIMEOUT 05 :TAG:-MAXLENGTH 05 :TAG:-ACTLENGTH 05 :TAG:-DATA

COMP PIC PIC COMP PIC COMP PIC COMP PIC PIC

S9(4). X(34) VALUE SPACE. S9(8) VALUE ZERO. S9(8) VALUE ZERO. S9(8). X(9999).

CVCSRECV 01 CSRECV. 05 RC 05 CONVID 05 TIMEOUT 05 MAXLENGTH 05 ACTLENGTH 05 DATA

COMP PIC PIC COMP PIC COMP PIC COMP PIC PIC

S9(4). X(34) VALUE SPACE. S9(8) VALUE ZERO. S9(8) VALUE ZERO. S9(8). X(9999).

CCSRLSE 01 :TAG:. 05 :TAG:-RC 05 :TAG:-CONVID

COMP PIC S9(4). PIC X(34)

VALUE SPACE.

CVCSRLSE 01 CSRLSE. 05 RC 05 CONVID

COMP PIC S9(4). PIC X(34)

VALUE SPACE.

76

VCOMPGM

CDSCONS 01 :TAG:. 05 :TAG:-RC COMP 05 :TAG:-DISTID 05 :TAG:-SECUR. 10 :TAG:-SECURLENGTH COMP 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT COMP 05 :TAG:-SENDERTAG 05 :TAG:-PARTNER 05 :TAG:-RECEIPT. 10 :TAG:-RECEIPTID 10 :TAG:-RECEIPTPARTNER 10 :TAG:-RECEIPTRC COMP 10 :TAG:-RECEIPTLENGTH COMP 10 :TAG:-RECEIPTDATA COMP 05 :TAG:-PRIO 05 :TAG:-INITIATOR

PIC S9(4). PIC X(34). PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8)

VALUE ZERO. VALUE SPACE. VALUE SPACE.

X(34) VALUE SPACE. X(8) VALUE SPACE. S9(4) VALUE ZERO. S9(4) VALUE ZERO. X(256). X(1) VALUE "N". X(8) VALUE SPACE.

CVDSCONS 01 DSCONS. 05 RC 05 DISTID 05 SECUR. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 PARTNER 05 RECEIPT. 10 RECEIPTID 10 RECEIPTPARTNER 10 RECEIPTRC 10 RECEIPTLENGTH 10 RECEIPTDATA 05 PRIO 05 INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC PIC COMP PIC COMP PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(34) X(8) S9(4) S9(4) X(256). X(1) X(8)

VALUE ZERO. VALUE SPACE. VALUE SPACE. VALUE VALUE VALUE VALUE SPACE. SPACE. ZERO. ZERO.

VALUE "N". VALUE SPACE.

Language

77

CDSCONR 01 :TAG:. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-SECUR. 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT 05 :TAG:-SENDERTAG 05 :TAG:-EXPEDITER 05 :TAG:-RECTYPE 05 :TAG:-INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(1). X(8)

VALUE ZERO. VALUE SPACE. VALUE SPACE. VALUE SPACE.

CVDSCONR 01 DSCONR. 05 RC 05 DISTID 05 SECUR. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 EXPEDITER 05 RECTYPE 05 INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC COMP PIC PIC PIC PIC PIC S9(4). X(99). S9(8) X(20) X(8) X(1). X(8)

VALUE ZERO. VALUE SPACE. VALUE SPACE. VALUE SPACE.

CDSSEND 01 :TAG:. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-LENGTH 05 :TAG:-DATA

COMP PIC PIC COMP PIC PIC

S9(4). X(34) VALUE SPACE. S9(8) VALUE ZERO. X(9999).

CVDSSEND 01 DSSEND. 05 RC 05 DISTID 05 LENGTH 05 DATA

COMP PIC PIC COMP PIC PIC

S9(4). X(34). VALUE SPACE. S9(8). VALUE ZERO. X(9999).

78

VCOMPGM

CDSRECV 01 :TAG:. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-MAXLENGTH 05 :TAG:-ACTLENGTH 05 :TAG:-DATA

COMP PIC PIC COMP PIC COMP PIC PIC

S9(4). X(34) VALUE SPACE. S9(8) VALUE ZERO. S9(8). X(9999).

CVDSRECV 01 DSRECV. 05 RC 05 DISTID 05 MAXLENGTH 05 ACTLENGTH 05 DATA

COMP PIC PIC COMP PIC COMP PIC PIC

S9(4). X(34) VALUE SPACE. S9(8) VALUE ZERO. S9(8). X(9999).

CDSRLSE 01 :TAG:. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-RVALUE

COMP PIC S9(4). PIC X(34) COMP PIC S9(4)

VALUE SPACE. VALUE ZERO.

CVDSRLSE 01 DSRLSE. 05 RC 05 DISTID 05 RVALUE

COMP PIC S9(4). PIC X(34) COMP PIC S9(4)

VALUE SPACE. VALUE ZERO.

CDSRCNS 01 :TAG:. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-SECUR. 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-PARTNER 05 :TAG:-INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC PIC PIC S9(4). X(99). X(8) X(8)

VALUE SPACE. VALUE SPACE.

CVDSRCNS 01 DSRCNS. 05 RC 05 DISTID 05 SECUR. 10 SECURLENGTH 10 SECURDATA 05 PARTNER 05 INITIATOR

COMP PIC S9(4). PIC X(34). COMP PIC PIC PIC PIC S9(4). X(99). X(8) X(8)

VALUE SPACE. VALUE SPACE.

Language

79

CDSPRLS 01 :TAG:. 05 :TAG:-RC 05 :TAG:-DISTID

COMP PIC S9(4). PIC X(34)

VALUE SPACE.

CVDSPRLS 01 DSPRLS. 05 RC 05 DISTID

COMP PIC S9(4). PIC X(34)

VALUE SPACE.

80

VCOMPGM

3.7
3.7.1

IDEAL for CICS

Parameter passing
The IDEAL interface uses the VCOM/CICS Cobol API. The Cobol API uses the LINK function. This means that it is not possible to supply a parameter list as usual when using the VCOM verbs. Instaed an area is passed that contains the parameters needed. Example:
CALL IDCSCONS USING W-IDCSCONS.IDCSCONSX

More examples can be found in Appendix A. Program examples on page 89.

Language

81

3.7.2

Copy text
The copytexts below is delivered with the VCOM software.

CSCONS 1 IDCSCONS 2 IDCSCONSX 2 FILLERX 3 RC 3 CONVID 3 SECURLENGTH 3 SECURDATA 3 TIMEOUT 3 SENDERTAG 3 PARTNER 3 INITIATOR

X U B X U B X U B X X X

177 REDEF IDCSCONSX 4 34 4 99 9 20 8 8

CSCONR 1 IDCSCONR 2 IDCSCONRX 2 FILLERX 3 RC 3 CONVID 3 SECURLENGTH 3 SECURDATA 3 TIMEOUT 3 SENDERTAG 3 EXPEDITER 3 INITIATOR

X U B X U B X U B X X X

177 REDEF IDCSCONRX 4 34 4 99 9 20 8 8

CSSEND 1 IDCSSEND 2 IDCSSENDX 2 FILLERX 3 RC 3 CONVID 3 LENGTH 3 DATA

X U B X U B X

10039 REDEF IDCSSENDX 4 34 9 9999

CSRECV 1 IDCSRECV 2 IDCSRECVX 2 FILLERX 3 RC 3 CONVID 3 TIMEOUT 3 MAXLENGTH 3 ACTLENGTH 3 DATA

X U X U U U X B B B B

10047 REDEF IDCSRECVX 4 34 9 9 9 9999

82

VCOMPGM

CSRLSE 1 IDCSRLSE 2 IDCSRLSEX 2 FILLERX 3 RC 3 CONVID

X U B X

36 REDEF IDCSRLSEX 4 34

DSCONS 1 IDDSCONS 2 IDDSCONSX 2 FILLERX 3 RC 3 DISTID 3 SECURLENGTH 3 SECURDATA 3 TIMEOUT 3 SENDERTAG 3 PARTNER 3 RECEIPTID 3 RECEIPTNAME 3 RECEIPTRC 3 RECEIPTLENGTH 3 RECEIPTDATA 3 PRIO 3 INITIATOR

X U X N X N X X X X N N X X X B B B

B B

480 REDEF IDDSCONSX 4 34 4 99 9 20 8 34 8 4 4 258 1 8

DSCONR 1 IDDSCONR 2 IDDSCONRX 2 FILLERX 3 RC 3 DISTID 3 SECURLENGTH 3 SECURDATA 3 TIMEOUT 3 SENDERTAG 3 EXPEDITER 3 RECTYPE 3 INITIATOR

X U B X N B X N B X X X X

178 REDEF IDDSCONRX 4 34 4 99 9 20 8 1 8

DSSEND 1 IDDSSEND 2 IDDSSENDX 2 FILLERX 3 RC 3 DISTID 3 LENGTH 3 DATA

X U B X N B X

10039 REDEF IDDSSENDX 4 34 9 9999

Language

83

DSRECV 1 IDDSRECV 2 IDDSRECVX 2 FILLERX 3 RC 3 DISTID 3 MAXLENGTH 3 ACTLENGTH 3 DATA

X U B X N B N B X

10043 REDEF IDDSRECVX 4 34 9 9 9999

DSRLSE 1 IDDSRLSE 2 IDDSRLSEX 2 FILLERX 3 RC 3 DISTID 3 RVALUE

X U B X N B

38 REDEF IDDSRLSEX 4 34 4

DCRCNS 1 IDDSRCNS 2 IDDSRCNSX 2 FILLERX 3 RC 3 DISTID 3 SECURLENGTH 3 SECURDATA 3 PARTNER 3 INITIATOR

X U B X N B X X X

153 REDEF IDDSRCNSX 4 34 4 99 8 8

DSPRLS 1 IDDSPRLS 2 IDDSPRLSX 2 FILLERX 3 RC 3 DISTID

X U B X

36 REDEF IDDSPRLSX 4 34

84

VCOMPGM

4.0

Environment
This section describes the programming and operation environment for VCOM.

4.1

Operation environment
VCOM is equipped with an online TSO/ISPF operator function. With this function it is possible to monitor conversations and distributions, view and change the VCOM configuration tables and also view different log files and test various functions. Most functions can also be performed on a remote VCOM system. The VCOM TSO/ISPF operator function can usually be reached by entering 'TSO VCOM' on the command line. Other ways may very well exist depending on the setup.

Environment

85

4.2

CICS
There is a specific VCOM/API to use in a CICS environment. It does not use the general API that is mentioned in other parts of this manual. It does however look the same to the VCOM monitor. VCOM is also able to start CICS transactions. This is done over a LU6.2 (APPC) session. No application data is sent over this connection.

4.2.1

Parallell transactions
When VCOM server initiates transactions in a CICS system they are received in a sequence mode, not in a parallell mode. This means that a VCOM transaction in a CICS system must finnish before the next VCOM transaction can start. As a VCOM transaction can be quite lengthy this will be a problem. To avoid this the transaction initiated by VCOM server should start another transaction (which executes the communication with the server) and then terminate. In this way VCOM server can initiate many transaction while CICS executes them in a parallell way. An example of such a program is seen in Figure 21 on page 84.

id division. program-id. VCOMPAR. author. vcom. environment division. configuration section. object-computer. ibm-370. data division. working-storage section. 01 w-resp pic s9(8) comp value zero.

procedure division. *----------------------------------------------* * MAIN Program main logic * *----------------------------------------------* main section. exec cics start transid ('APL1') resp (w-resp) end-exec if w-resp not = dfhresp(normal) evaluate w-resp when dfhresp(invreq) . . <=== perform error handling . end-evaluate end-if exec cics return end-exec . main-end. goback. Figure 21. Proram for enabling parallell CICS transasction

86

VCOMPGM

4.3

IMS
VCOM is able to start IMS transactions in an IMS MPP. This is done by sending the transaction code to IMS through an IMS LU6.2 Adapter or by using IMS/APPC. No user data is transferred over this session together with the transaction code. All user data is transferred with standard VCOM calls through standard VCOM API. There is no terminal assoiciated with IMS and therefore the IMS transaction should be generated with option NORESP. The application should not try to do insert to the I/O PCB of the same reason. An example of a typical service program is shown in Figure 22 on page 85.

initiation read message from I/O PCB call CSCONR ... if OK then call CSRECV ... if OK then action call CSSEND ... else error handling endif else error handling end if call CSRLSE ... end of program note: no insert to I/O PCB receive question short timeout

send answer

Figure 22.

Coding of IMS/VCOM transaction.

Environment

87

4.4

Batch
An application program using VCOM can also be executed as a batch job. This batch job can also be started by VCOM when a distribution is received or a conversation is requested. The expediter table defines if VCOM shall start the receiving program. The following information is needed by VCOM to be able to submit a batch job. The name of the dataset that contains the JCL member. The name of the member to submit. What user id to assign to the job. If this is not specified a default user id will be used.

When there are many submissions at the same time, the jobs will be queued in the JES system due to duplicate names. This problem can however be bypassed using a question mark (?) in the 8th position of the jobname. VCOM will then substitute the question mark character with another character thus making the jobname unique.

4.5

TSO
A VCOM program may be run in a TSO session. It is also possible to run TSO in batch. This can be useful when using REXX programs.

4.6

Started task
An application program using VCOM can also be executed as a started task.

88

VCOMPGM

5.0

Common problems
This section is intentionally left blank.

Common problems

89

90

VCOMPGM

Appendix A. Program examples

This appendix includes programming examples for both conversation and distribution. The languages included are Cobol, Fortran, C, REXX and Assembler. The programs in this appendix has no intention of showing the exact way to write VCOM applications. It describes the VCOM calls in different languages.

Appendix A. Program examples

91

A.1
A.1.1

Cobol program
Conversation initiator

ID DIVISION. PROGRAM-ID. CCLIENT AUTHOR. N.N SKIP2 *REMARKS. * *---------------------------------------------------------* * SAMPLE CONVERSATION PROGRAM * * * * THE PROGRAM ACTS AS A CLIENT IN THAT SENSE * * THAT IT ISSUES QUESTIONS THAT A SERVER THEN * * ANSWERS. * * FIRST THE PARTNER ID IS RETRIEVED FROM THE * * TERMINAL. * * NEXT THE CLIENT CONNECTS TO THE SERVER AND * * THEN FETCH THE QUESTION FROM THE TERMINAL AND * * SENDS IT TO THE SERVER. THEN THE CLIENT WAITS * * FOR THE ANSWER AND WHEN IT ARRIVES IT IS * * DISPLAYED ON THE TERMINAL. * * THE CONVERSATION IS ENDED BY THE CLIENT * * WHEN THE STRING XXX IS RETRIEVED FROM THE TERMINAL * * * *---------------------------------------------------------* * EJECT ENVIRONMENT DIVISION. SKIP2 DATA DIVISION. WORKING-STORAGE SECTION. 77 PROGRAM-NAME SKIP2 PIC X(8) VALUE 'CCLIENT'.

SKIP2 DYNAMIC-SUBPROGRAMS. 03 CSSEND PIC X(8) 03 CSRECV PIC X(8) 03 CSRLSE PIC X(8) 03 CSCONS PIC X(8) 03 CSCONR PIC X(8) EJECT -COPY COPYTEXT -PRE VCAEJECT 01 DIV. 03 QUESTION PIC X(50) 03 ANSWER PIC X(50) 03 PARTNER PIC X(8) SKIP3 EJECT PROCEDURE DIVISION. 01

VALUE VALUE VALUE VALUE VALUE

'CSSEND 'CSRECV 'CSRLSE 'CSCONS 'CSCONR

'. '. '. '. '.

VALUE SPACE. VALUE SPACE. VALUE SPACE.

92

VCOMPGM

* *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION. SKIP2 PERFORM A-INIT PERFORM B-PROCESS PERFORM Z-FINIT DISPLAY ' GOBACK CONTINUE. EJECT * *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION. SKIP2 MOVE +120 TO VCA-TIMEOUT MOVE SPACE TO VCA-SECUR-DATA MOVE ZERO TO VCA-SECUR-LENGTH MOVE ZERO TO VCA-ACTLENGTH MOVE +50 TO VCA-LENGTH MOVE +50 TO VCA-MAXLENGTH MOVE SPACE TO VCA-SENDERTAG MOVE PARTNER TO VCA-PARTNER MOVE SPACE TO VCA-INITIATOR CONTINUE. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS SECTION. SKIP2 PERFORM BA-CONNECT-SEND PERFORM BB-PROCESS PERFORM BC-DISCONNECT-SEND CONTINUE. CCLIENT OK '

EJECT

Appendix A. Program examples

93

* *---------------------------------------------------------* * GET INPUT FROM TERMINAL ABOUT PARTNER NAME AND * * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. * * IF ERROR DISPLAY ERRORCODE. * *---------------------------------------------------------* * BA-CONNECT-SEND SECTION. SKIP2 DISPLAY 'ENTER PARTNER NAME: ' ACCEPT PARTNER MOVE PARTNER TO VCA-PARTNER CALL CSCONS USING VCA-RC VCA-CONVID VCA-SECUR VCA-TIMEOUT VCA-SENDERTAG VCA-PARTNER VCA-INITIATOR END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSCONS IN CCLIENT ' VCA-RC PERFORM BC-DISCONNECT-SEND GOBACK END-IF CONTINUE. EJECT * *---------------------------------------------------------* * GET INPUT FROM TERMINAL ABOUT QUESTION AND * * SEND THE QUESTION TO THE SERVER PROGRAM. * * KEEP ON DOING THIS UNTIL XXX IS RECEIVED. * * IF ERROR, DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BB-PROCESS SECTION. SKIP2 DISPLAY 'QUESTION: ' ACCEPT QUESTION PERFORM UNTIL QUESTION = 'XXX' PERFORM BBA-SEND PERFORM BBA-RECEIVE DISPLAY 'ANSWER; ' ANSWER DISPLAY 'QUESTION: ' ACCEPT QUESTION END-PERFORM CONTINUE. EJECT

94

VCOMPGM

* *---------------------------------------------------------* * RETRIVE THE ANSWER FROM VCOM USING THE RECEIVE VERB. * * IF ERROR, DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-RECEIVE SECTION. SKIP2 MOVE SPACE TO VCA-DATA CALL CSRECV USING VCA-RC VCA-CONVID VCA-TIMEOUT VCA-MAXLENGTH VCA-ACTLENGTH VCA-DATA END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSRECV IN CCLIENT ' VCA-RC PERFORM BC-DISCONNECT-SEND GOBACK END-IF MOVE VCA-DATA TO ANSWER CONTINUE. EJECT * *---------------------------------------------------------* * ISSUE A SEND OF THE QUESTION TO THE SERVER. * * IF ERROR, DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-SEND SECTION. SKIP2 MOVE QUESTION TO VCA-DATA CALL CSSEND USING VCA-RC VCA-CONVID VCA-LENGTH VCA-DATA END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSSEND IN CCLIENT ' VCA-RC PERFORM BC-DISCONNECT-SEND GOBACK END-IF CONTINUE. EJECT

Appendix A. Program examples

95

* *---------------------------------------------------------* * DISCONNECT THE CONVERSATION. * *---------------------------------------------------------* * BC-DISCONNECT-SEND SECTION. SKIP2 CALL CSRLSE USING VCA-RC VCA-CONVID END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSRLSE IN CCLIENT ' VCA-RC GOBACK END-IF CONTINUE. EJECT * *---------------------------------------------------------* * END * *---------------------------------------------------------* * Z-FINIT SECTION. SKIP2 CONTINUE.

96

VCOMPGM

A.1.2

Conversation responder

ID DIVISION. PROGRAM-ID. CSERVER AUTHOR. N.N SKIP2 *REMARKS. * *---------------------------------------------------------* * SAMPLE CONVERSATION PROGRAM * * * * THE PROGRAM ACTS AS A SERVER IN THAT SENSE * * THAT IT RECEIVES QUESTIONS FROM A CLIENT AND * * RETURN AN ANSWER. * * FIRST THE SERVER SET A CONNECT REQUEST AND WAITS * * FOR A CLIENT TO CONNECT. NEXT THE QUESTION IS * * RECEIVED AND GIVES AN ANSWER. THE SERVER THEN WAITS* * FOR THE NEXT QUESTION AND KEEP DOING THIS UNTIL * * XXX, TIMEOUT OR ERROR IS RECEIVED. * * * *---------------------------------------------------------* * EJECT ENVIRONMENT DIVISION. SKIP2 DATA DIVISION. WORKING-STORAGE SECTION. 77 PROGRAM-NAME PIC X(8) VALUE 'CSERVER'.

SKIP2 DYNAMIC-SUBPROGRAMS. 03 CSSEND PIC X(8) 03 CSRECV PIC X(8) 03 CSRLSE PIC X(8) 03 CSCONS PIC X(8) 03 CSCONR PIC X(8) EJECT -COPY COPYTTEXT -PRE VCAEJECT 01 DIV. 03 QUESTION PIC X(50) 03 ANSWER PIC X(50) 03 EXPEDITER PIC X(8) SKIP3 EJECT PROCEDURE DIVISION. 01

VALUE VALUE VALUE VALUE VALUE

'CSSEND 'CSRECV 'CSRLSE 'CSCONS 'CSCONR

'. '. '. '. '.

VALUE SPACE. VALUE SPACE. VALUE SPACE.

Appendix A. Program examples

97

* *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION. SKIP2 PERFORM A-INIT PERFORM B-PROCESS PERFORM Z-FINIT DISPLAY ' GOBACK CONTINUE. EJECT * *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION. SKIP2 MOVE +120 TO VCA-TIMEOUT MOVE SPACE TO VCA-SECUR-DATA MOVE ZERO TO VCA-SECUR-LENGTH MOVE ZERO TO VCA-ACTLENGTH MOVE +50 TO VCA-LENGTH MOVE +50 TO VCA-MAXLENGTH MOVE SPACE TO VCA-SENDERTAG MOVE EXPEDITER TO VCA-EXPEDITER CONTINUE. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS SECTION. SKIP2 PERFORM BA-CONNECT-RECEIVE PERFORM BB-PROCESS PERFORM BC-DISCONNECT-RECEIVE CONTINUE. EJECT CSERVER OK '

98

VCOMPGM

* *---------------------------------------------------------* * GET INPUT FROM TERMINAL ABOUT EXPEDITER NAME AND * * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. * * IF ERROR DISPLAY ERRORCODE. * *---------------------------------------------------------* * BA-CONNECT-RECEIVE SECTION. SKIP2 DISPLAY 'ENTER EXPEDITER NAME: ' ACCEPT EXPEDITER MOVE EXPEDITER TO VCA-EXPEDITER CALL CSCONR USING VCA-RC VCA-CONVID VCA-SECUR VCA-TIMEOUT VCA-SENDERTAG VCA-EXPEDITER VCA-INITIATOR END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSCONR IN CSERVER ' VCA-RC PERFORM BC-DISCONNECT-RECEIVE GOBACK END-IF CONTINUE. EJECT * *---------------------------------------------------------* * GET INPUT FROM VCOM ABOUT QUESTION AND * * DISPLAY IT ON THE TERMINAL. RETRIVE INPUT * * FROM TERMINAL AND RETURN IT TO THE CLIENT * * AS THE ANSWER. * * KEEP ON DOING THIS UNTIL XXX IS RECEIVED. * * IF ERROR, DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BB-PROCESS SECTION. SKIP2 PERFORM BBA-RECEIVE DISPLAY 'QUESTION; ' QUESTION PERFORM UNTIL QUESTION = 'XXX' DISPLAY 'ANSWER: ' ACCEPT ANSWER PERFORM BBA-SEND PERFORM BBA-RECEIVE DISPLAY 'QUESTION; ' QUESTION END-PERFORM CONTINUE. EJECT

Appendix A. Program examples

99

* *---------------------------------------------------------* * RETRIVE THE ANSWER FROM VCOM BY A RECEIVE. * * IF ERROR, DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-RECEIVE SECTION. SKIP2 MOVE SPACE TO VCA-DATA CALL CSRECV USING VCA-RC VCA-CONVID VCA-TIMEOUT VCA-MAXLENGTH VCA-ACTLENGTH VCA-DATA END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSRECV IN CSERVER ' VCA-RC PERFORM BC-DISCONNECT-RECEIVE GOBACK END-IF MOVE VCA-DATA TO QUESTION CONTINUE. EJECT * *---------------------------------------------------------* * ISSUE A SEND OF THE ANSWER TO THE CLIENT. * * IF ERROR, DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-SEND SECTION. SKIP2 MOVE ANSWER TO VCA-DATA CALL CSSEND USING VCA-RC VCA-CONVID VCA-LENGTH VCA-DATA END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSSEND IN CSERVER ' VCA-RC PERFORM BC-DISCONNECT-RECEIVE GOBACK END-IF CONTINUE. EJECT

100

VCOMPGM

* *---------------------------------------------------------* * DISCONNECT THE CONVERSATION. * *---------------------------------------------------------* * BC-DISCONNECT-RECEIVE SECTION. SKIP2 CALL CSRLSE USING VCA-RC VCA-CONVID END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT CSRLSE IN CSERVER ' VCA-RC GOBACK END-IF CONTINUE. EJECT * *---------------------------------------------------------* * END * *---------------------------------------------------------* * Z-FINIT SECTION. SKIP2 CONTINUE.

Appendix A. Program examples

101

A.1.3

Distribution initiator

ID DIVISION. PROGRAM-ID. DSEND AUTHOR. N.N SKIP2 *REMARKS. * *---------------------------------------------------------* * SAMPLE DISTRIBUTION SEND PROGRAM * * * * THE PROGRAM CONNECT TO A PARTNER AND IF * * SUCCESSFULL A DATASET IS OPEN FOR INPUT. * * THE DATASET SET IS READ AND EACH RECORD * * IS SENT TO VCOM. FINALLY THE DATASET IS * * CLOSED AND THE CONNECTION TO VCOM IS RELEASED. * * * *---------------------------------------------------------* * EJECT ENVIRONMENT DIVISION. SKIP2 INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT SENDFILE DATA DIVISION. SKIP2 FILE SECTION. FD SENDFILE LABEL RECORD STANDARD RECORDING F BLOCK CONTAINS 0. SENDFIEL-REC EJECT PIC X(80). ASSIGN TO UT-S-DSENDDD.

01

102

VCOMPGM

WORKING-STORAGE SECTION. 77 77 77 77 77 77 77 01 PROGRAM-NAME YES NO SENDFILE-EOF REC-LTH RCODE RCODE-1000 SKIP2 GENERAL-CONSTANTS. 03 03 03 S T PARTNER PIC X(8) VALUE 'DSEND PIC PIC PIC PIC X X X S9(5) '.

VALUE 'Y'. VALUE 'N'. VALUE 'N'. COMP-3 VALUE +80. COMP SYNC COMP SYNC VALUE +0. VALUE +1000.

PIC S9(4) PIC S9(4)

PIC X PIC X PIC X(8)

VALUE 'S'. VALUE 'T'. VALUE 'TMATSA '.

SKIP2 DYNAMIC-SUBPROGRAMS. 03 DSSEND PIC X(8) 03 DSRECV PIC X(8) 03 DSRLSE PIC X(8) 03 DSCONS PIC X(8) 03 DSCONR PIC X(8) EJECT -COPY COPYTEXT -PRE VCAEJECT 01 SENDFILE-AREA. 03 SENDFILE-REC PIC X(3500). SKIP3 EJECT PROCEDURE DIVISION. 01

VALUE VALUE VALUE VALUE VALUE

'DSSEND 'DSRECV 'DSRLSE 'DSCONS 'DSCONR

'. '. '. '. '.

* *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION. SKIP2 PERFORM A-INIT PERFORM B-PROCESS-THE-FILE PERFORM Z-FINIT MOVE RCODE TO RETURN-CODE DISPLAY ' DSEND OK ' GOBACK CONTINUE. EJECT

Appendix A. Program examples

103

* *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION. SKIP2 MOVE SPACE TO VCA-SECUR-DATA MOVE ZERO TO VCA-SECUR-LENGTH MOVE -1 TO VCA-TIMEOUT MOVE SPACE TO VCA-SENDERTAG MOVE PARTNER TO VCA-PARTNER MOVE SPACE TO VCA-INITIATOR MOVE SPACE TO VCA-RECEIPT-PARTNER MOVE ZERO TO VCA-RECEIPT-RC MOVE ZERO TO VCA-RECEIPT-LENGTH MOVE SPACE TO VCA-RECEIPT-DATA MOVE 'N' TO VCA-PRIO MOVE +1 TO VCA-RVALUE OPEN INPUT SENDFILE CONTINUE. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS-THE-FILE SECTION. SKIP2 PERFORM S10-READ-SENDFILE IF SENDFILE-EOF = NO PERFORM BA-CONNECT-SEND PERFORM UNTIL SENDFILE-EOF = YES PERFORM BB-PROCESS-A-RECORD PERFORM S10-READ-SENDFILE END-PERFORM PERFORM BC-DISCONNECT-SEND END-IF CONTINUE. EJECT

104

VCOMPGM

* *---------------------------------------------------------* * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. * * AT END DISPLAY DISTID AND SENDERTAG. * * IF ERROR DISPLAY ERRORCODE. * *---------------------------------------------------------* * BA-CONNECT-SEND SECTION. SKIP2 CALL DSCONS USING VCA-RC VCA-DISTID VCA-SECUR VCA-TIMEOUT VCA-SENDERTAG VCA-PARTNER VCA-RECEIPT VCA-PRIO VCA-INITIATOR END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT DSCONS IN DSEND ' VCA-RC MOVE 0 TO VCA-RVALUE PERFORM BC-DISCONNECT-SEND MOVE RCODE-1000 TO RETURN-CODE GOBACK END-IF DISPLAY 'DISTID: ' VCA-DISTID CONTINUE. EJECT * *---------------------------------------------------------* * PROCESS A RECORD. MOVE LENGTH AND DATA AND THEN * * ISSUE THE SEND. * *---------------------------------------------------------* * BB-PROCESS-A-RECORD SECTION. SKIP2 MOVE REC-LTH TO VCA-LENGTH MOVE SENDFILE-AREA TO VCA-DATA PERFORM BBA-SEND CONTINUE. EJECT

Appendix A. Program examples

105

* *---------------------------------------------------------* * SET UP A SEND. * * IF ERROR DISPLAY THE RETURN CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-SEND SECTION. SKIP2 CALL DSSEND USING VCA-RC VCA-DISTID VCA-LENGTH VCA-DATA END-CALL

IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT DSSEND IN DSEND ' VCA-RC MOVE 0 TO VCA-RVALUE PERFORM BC-DISCONNECT-SEND MOVE RCODE-1000 TO RETURN-CODE GOBACK END-IF CONTINUE. EJECT * *---------------------------------------------------------* * DO THE RELEASE. * * RVALUE CONTROLS THE ACTION * * 1 DELIVER THE DISTRIBUTION * * NOT 1 DISCARD THE DISTRIBUTION * * IF ERROR DISPLAY THE RETURN CODE. * *---------------------------------------------------------* * BC-DISCONNECT-SEND SECTION. SKIP2 CALL DSRLSE USING VCA-RC VCA-DISTID VCA-RVALUE END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT DSRLSE IN DSEND ' VCA-RC MOVE RCODE-1000 TO RETURN-CODE GOBACK END-IF CONTINUE. EJECT

106

VCOMPGM

* *---------------------------------------------------------* * END * *---------------------------------------------------------* * Z-FINIT SECTION. SKIP2 CLOSE SENDFILE CONTINUE. EJECT * *---------------------------------------------------------* * READ ROUTINE * *---------------------------------------------------------* * S10-READ-SENDFILE SECTION. SKIP2 READ SENDFILE INTO SENDFILE-AREA AT END MOVE YES TO SENDFILE-EOF END-READ CONTINUE.

Appendix A. Program examples

107

A.1.4

Distribution responder

ID DIVISION. PROGRAM-ID. DRECEIVE AUTHOR. MATS ANDERSSON DATE-WRITTEN. MARS 1993 SKIP2 *REMARKS. * *---------------------------------------------------------* * SAMPLE DISTRIBUTION RECEIVE PROGRAM * * * * THE PROGRAM CONNECTS TO AN EXPEDITER AND IF * * SUCCESSFUL A DATASET IS OPENED FOR OUTPUT. * * RECORDS ARE THEN RECEIVED FROM VCOM AND * * STORED IN THE DATASET. FINALLY THE DATESET IS * * CLOSED AND THE CONNECTION TO VCOM IS RELEASED. * * * *---------------------------------------------------------* * EJECT ENVIRONMENT DIVISION. SKIP2 INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT RECVFILE DATA DIVISION. SKIP2 FILE SECTION. FD RECVFILE LABEL RECORD STANDARD RECORDING F BLOCK CONTAINS 0. RECVFILE-REC PIC X(80). ASSIGN TO UT-S-DRECVDD.

01

108

VCOMPGM

WORKING-STORAGE SECTION. 77 77 77 77 01 PROGRAM-NAME RCODE RCODE-45 RCODE-1000 SKIP2 GENERAL-CONSTANTS. 03 03 EXPEDITER RECVAREA PIC X(8) PIC S9(4) PIC S9(4) PIC S9(4) VALUE 'DRECEIVE'. COMP SYNC COMP SYNC COMP SYNC VALUE +0. VALUE +45. VALUE +1000.

PIC X(8) PIC X(80)

VALUE 'TMATSA VALUE SPACE.

'.

SKIP2 DYNAMIC-SUBPROGRAMS. 03 DSSEND PIC X(8) 03 DSRECV PIC X(8) 03 DSRLSE PIC X(8) 03 DSCONS PIC X(8) 03 DSCONR PIC X(8) EJECT -COPY COPYTEXT -PRE VCAEJECT PROCEDURE DIVISION. 01

VALUE VALUE VALUE VALUE VALUE

'DSSEND 'DSRECV 'DSRLSE 'DSCONS 'DSCONR

'. '. '. '. '.

* *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION. SKIP2 PERFORM A-INIT PERFORM B-PROCESS PERFORM Z-FINIT MOVE RCODE TO RETURN-CODE GOBACK CONTINUE. EJECT

Appendix A. Program examples

109

* *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION. SKIP2 MOVE SPACE TO VCA-SECUR-DATA MOVE ZERO TO VCA-SECUR-LENGTH MOVE +30 TO VCA-TIMEOUT MOVE SPACE TO VCA-SENDERTAG MOVE EXPEDITER TO VCA-EXPEDITER MOVE ZERO TO VCA-RVALUE CONTINUE. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS SECTION. SKIP2 PERFORM BA-CONNECT-RECEIVE IF VCA-RC = ZERO PERFORM BB-PROCESS PERFORM BC-DISCONNECT-RECEIVE END-IF CONTINUE. EJECT

110

VCOMPGM

* *---------------------------------------------------------* * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. * * AT END DISPLAY DISTID AND SENDERTAG. * * IF ERROR DISPLAY ERRORCODE. * *---------------------------------------------------------* * BA-CONNECT-RECEIVE SECTION. SKIP2 CALL DSCONR USING VCA-RC VCA-DISTID VCA-SECUR VCA-TIMEOUT VCA-SENDERTAG VCA-EXPEDITER VCA-RECTYPE VCA-INITIATOR END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT DSCONR IN DRECEIVE ' VCA-RC MOVE RCODE-1000 TO RETURN-CODE MOVE -2 TO VCA-RVALUE PERFORM BC-DISCONNECT-RECEIVE GOBACK END-IF DISPLAY 'DISTID: ' VCA-DISTID DISPLAY 'SENDERTAG: ' VCA-SENDERTAG OPEN OUTPUT RECVFILE CONTINUE. EJECT * *---------------------------------------------------------* * PROCESS THE DISTRIBUTION. KEEP ON RECEIVING UNTIL * * THERE ARE NO MORE RECORDS TO RECEIVE. WRITE ALL * * RECORDS TO A FILE. * *---------------------------------------------------------* * BB-PROCESS SECTION. SKIP2 PERFORM BBA-RECEIVE PERFORM UNTIL VCA-RC NOT = ZERO MOVE VCA-DATA TO RECVAREA PERFORM S10-WRITE-RECVFILE PERFORM BBA-RECEIVE END-PERFORM CONTINUE. EJECT

Appendix A. Program examples

111

* *---------------------------------------------------------* * SET UP A RECEIVE. * * IF ERROR DISPLAY THE RETURN CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-RECEIVE SECTION. SKIP2 CALL DSRECV USING VCA-RC VCA-DISTID VCA-MAXLENGTH VCA-ACTLENGTH VCA-DATA END-CALL

IF VCA-RC NOT = ZERO AND VCA-RC NOT = RCODE-45 DISPLAY 'ERROR RC AT DSRECV IN DRECEIVE ' VCA-RC MOVE RCODE-1000 TO RETURN-CODE MOVE -2 TO VCA-RVALUE PERFORM BC-DISCONNECT-RECEIVE GOBACK END-IF CONTINUE. EJECT * *---------------------------------------------------------* * DO THE RELEASE. * * ALWAYS CLOSE DATASET BEFORE RELEASE AND TEST * * RETURN CODE. * * RVALUE CONTROLS THE ACTION * * -1 IS ROLLBACK * * -2 IS HOLD * * IF ERROR DISPLAY THE RETURN CODE. * *---------------------------------------------------------* * BC-DISCONNECT-RECEIVE SECTION. SKIP2 CLOSE RECVFILE CALL DSRLSE USING VCA-RC VCA-DISTID VCA-RVALUE END-CALL IF VCA-RC NOT = ZERO DISPLAY 'ERROR RC AT DSRLSE IN DRECEIVE ' VCA-RC MOVE RCODE-1000 TO RETURN-CODE GOBACK END-IF CONTINUE. EJECT

112

VCOMPGM

* *---------------------------------------------------------* * END * *---------------------------------------------------------* * Z-FINIT SECTION. SKIP2 CONTINUE. EJECT * *---------------------------------------------------------* * WRITE ROUTINE * *---------------------------------------------------------* * S10-WRITE-RECVFILE SECTION. SKIP2 WRITE RECVFILE-REC FROM RECVAREA CONTINUE. EJECT

Appendix A. Program examples

113

A.2
A.2.1

Fortran program
Conversation initiator

************************************************************************ * * PROGRAM: CSS * * DESCRIPTION: Connect as a initiator. Send a record and receive * one and then disconnect. * ************************************************************************ * * GLOBAL RESOURCES: ( Excl Subroutines ) * * Files: ( Excl files 5 and 6 ) * * Common data blocks: * ************************************************************************ * Program CSS * Implicit NONE * * GLOBAL REFERENCES: ( Excl Calls ) * * LOCAL OBJECTS: * Variables: Integer*2 secur_lth /0/ * security length Character*99 secur * security Character*20 sendertag /'FORTTEST'/ * sendertag Character*8 partner /'VTTMAC1'/ * partner Character*8 expediter * expediter Character*8 initiator * initiator Character*80 wbuf/'HUBBA* '/,rbuf * buffers Character*34 convid * conversation id Character*34 rcpid * rcpt dist id Character*8 rcppart /' '/ * rcpt partner Character*40 rcpdata * rcpt partner Character*1 prio /'E'/ * prio Integer*2 rc * return code Integer*2 rvalue /1/ * rvalue Integer*2 rcprc /-1/ * return code Integer timeout /20/ * timeout Integer rlen,wlen,arlen * lengths Integer rcplth /0/ * lengths

114

VCOMPGM

* * PROCEDURE DIVISION: * wlen=LEN(wbuf) rlen=LEN(rbuf) secur_lth=0 * Call CSCONS(rc,convid,secur_lth,secur,timeout, & sendertag,partner,initiator) Write(*,*)'DSCONS rc=',rc Call CSSEND(rc,convid,wlen,wbuf) * Send question Write(*,*)'DSSEND rc=',rc Call CSRECV(rc,convid,timeout,rlen,rlen,rbuf) * Receive answer Write(*,*)'DSRECV rc=',rc Call CSRLSE(rc,convid) * Avsluta conv. Write(*,*)'CSRLSE rc=',rc * END

Appendix A. Program examples

115

A.2.2

Conversation responder

************************************************************************ * * PROGRAM: CSR * * DESCRIPTION: Connect as a responder. receive a record and send * one and then disconnect. * ************************************************************************ * * GLOBAL RESOURCES: ( Excl Subroutines ) * * Files: ( Excl files 5 and 6 ) * * Common data blocks: * ************************************************************************ * Program CSR * Implicit NONE * * GLOBAL REFERENCES: ( Excl Calls ) * * LOCAL OBJECTS: * Variables: Integer*2 secur_lth /0/ * security length Character*99 secur * security Character*20 sendertag /'FORTTEST'/ * sendertag Character*8 partner /'VTTMAC1'/ * partner Character*8 expediter /'VTTMAC1'/ * expediter Character*8 initiator * initiator Character*80 wbuf/'BABBA* '/,rbuf * buffers Character*34 convid * conversation id Character*34 rcpid * rcpt dist id Character*8 rcppart /' '/ * rcpt partner Character*40 rcpdata * rcpt partner Character*1 prio /'E'/ * prio Integer*2 rc * return code Integer*2 rvalue /1/ * rvalue Integer*2 rcprc /-1/ * return code Integer timeout /20/ * timeout Integer rlen,wlen,arlen * lengths Integer rcplth /0/ * lengths

116

VCOMPGM

* * PROCEDURE DIVISION: * wlen=LEN(wbuf) rlen=LEN(rbuf) secur_lth=0 * Call CSCONR(rc,convid,secur_lth,secur,timeout, & sendertag,expediter,initiator) Write(*,*)'DSCONR rc=',rc Call CSRECV(rc,convid,timeout,rlen,rlen,rbuf) * Receive question Write(*,*)'DSRECV rc=',rc Call CSSEND(rc,convid,wlen,wbuf) * Send answer Write(*,*)'DSSEND rc=',rc Call CSRLSE(rc,convid) Write(*,*)'CSRLSE rc=',rc * END

Appendix A. Program examples

117

A.2.3

Distribution initiator

************************************************************************ * * PROGRAM: DSS * * DESCRIPTION: SEND A VCOM DISTRIBUTION * ************************************************************************ * * GLOBAL RESOURCES: ( Excl Subroutines ) * * Files: ( Excl files 5 and 6 ) * * Common data blocks: * ************************************************************************ * Program DSS * Implicit NONE * * GLOBAL REFERENCES: ( Excl Calls ) * * LOCAL OBJECTS: * Variables: Integer*2 secur_lth /0/ * security length Character*99 secur * security Character*20 sendertag /'FORTTEST'/ * sendertag Character*8 partner /'VTTMAD1'/ * partner Character*8 expediter * expediter Character*8 initiator * initiator Character*80 wbuf/'HUBBA'/,rbuf * buffers Character*34 convid * conversation id Character*34 rcpid * rcpt dist id Character*8 rcppart /' '/ * rcpt partner Character*40 rcpdata * rcpt partner Character*1 prio /'E'/ * prio Integer*2 rc * return code Integer*2 rvalue /1/ * rvalue Integer*2 rcprc /-1/ * return code Integer timeout /-1/ * timeout Integer rlen,wlen,arlen * lengths Integer rcplth /0/ * lengths

* * PROCEDURE DIVISION: * wlen=LEN(wbuf) secur_lth=0 * Call DSCONS(rc,convid,secur_lth,secur,timeout, & sendertag,partner, & rcpid,rcppart,rcprc,rcplth,rcpdata,prio) Call DSSEND(rc,convid,wlen,wbuf) Call DSRLSE(rc,convid,rvalue) * END

118

VCOMPGM

A.2.4

Distribution responder

************************************************************************ * * PROGRAM: DSS * * DESCRIPTION: Receive a VCOM distribution * ************************************************************************ * * GLOBAL RESOURCES: ( Excl Subroutines ) * * Files: ( Excl files 5 and 6 ) * * Common data blocks: * ************************************************************************ * Program DSS * Implicit NONE * * GLOBAL REFERENCES: ( Excl Calls ) * * LOCAL OBJECTS: * Variables: Integer*2 secur_lth /0/ * security length Character*99 secur * security Character*20 sendertag /'FORTTEST'/ * sendertag Character*8 partner /'VTTMAD1'/ * partner Character*8 expediter /'VTTMAD1'/ * expediter Character*8 initiator /' '/ * initiator Character*80 wbuf/' '/,rbuf * buffers Character*34 convid * conversation id Character*34 rcpid * rcpt dist id Character*8 rcppart /' '/ * rcpt partner Character*40 rcpdata * rcpt partner Character*1 prio /'E'/ * prio Character*1 rectyp /' '/ * rec typ Integer*2 rc * return code Integer*2 rvalue /1/ * rvalue Integer*2 rcprc /-1/ * return code Integer timeout /-1/ * timeout Integer rlen,wlen,arlen * lengths Integer rcplth /0/ * lengths

* * PROCEDURE DIVISION: * rlen=LEN(rbuf) secur_lth=0 * Call DSCONR(rc,convid,secur_lth,secur,timeout, & sendertag,expediter, & rectyp,initiator) Call DSRECV(rc,convid,rlen,rlen,rbuf) Call DSRLSE(rc,convid,rvalue) * END

Appendix A. Program examples

119

A.3
A.3.1

C program
Conversation initiator

#include <stdio.h> #include <string.h> #include "vcom.h" main(int argc, char *argv ) { CSID csid; long tmo, len; short rc; char data 50; SECINFO secur; secur.usdlen = 0; tmo = 30; cscons(&rc, &csid, &secur, &tmo, "This is a test", argv 1, "INIT00"); if (rc != VCOM_RC_SUCCESS) { printf("cscons failed, rc = %dn", rc); exit(1); } while(1) { printf("Enter data: "); if (gets(data) == 0) break; len = strlen(data) + 1; cssend(&rc, &csid, &len, data); if (rc != VCOM_RC_SUCCESS) { printf("cssend failed, rc = %dn", rc); break; } } csrlse(&rc, &csid); putchar('n'); }

120

VCOMPGM

A.3.2

Conversation responder

#include <stdio.h> #include <string.h> #include "vcom.h" main(int argc, char *argv ) { short rc; CSID csid; SECINFO secur; long tmo; long len, maxlen; char sendertag 20; char data 50; secur.usdlen = 0; tmo = 60; csconr(&rc, &csid, &secur, &tmo, sendertag, argv 1, NULL); if (rc != VCOM_RC_SUCCESS) { printf("csconr failed, rc = %dn", rc); exit(1); } maxlen = sizeof(data); while (1) { csrecv(&rc, &csid, &tmo, &maxlen, &len, data); if (rc == VCOM_RC_RLSE_SESS) break; if (rc != VCOM_RC_SUCCESS) { printf("csrecv failed, rc = %dn", rc); break; } printf("Received data: '%s'n", data); } csrlse(&rc, &csid); }

Appendix A. Program examples

121

A.3.3

Distribution initiator

#include <stdio.h> #include <string.h> #include "vcom.h" main(int argc, char *argv ) { DSID dsid; long tmo, len; short rc=0; char data 50; SECINFO secur; RECEIPT recp; short rvalue; char prio; int i; secur.usdlen = 0; tmo = -1; memset(recp.partner, ' ', 8); prio = 'N'; dscons(&rc, &dsid, &secur, &tmo, "DS TEST "VTTMAD1 ", &recp, &prio, "INIT00 "); if (rc >= VCOM_RC_SUCCESS) { printf("dscons failed, rc = %dn", rc); exit(1); }

",

for (i = 0; i < 2; i++) { sprintf(data, "Post nr %d, This is some test data", i); len = strlen(data) + 1; dssend(&rc, &dsid, &len, data); if (rc >= VCOM_RC_SUCCESS) { printf("dssend failed, rc = %dn", rc); break; } } rvalue = VCOM_RC_SUCCESS; dsrlse(&rc, &dsid, &rvalue); putchar('n'); }

122

VCOMPGM

A.3.4

Distribution responder

#include <stdio.h> #include <string.h> #include "vcom.h" main(int argc, char *argv ) { short rc; DSID dsid; SECINFO secur; long tmo; long len, maxlen; char sendertag 20; char data 50; char rectype; short rvalue; secur.usdlen = 0; tmo = -1; dsconr(&rc, &dsid, &secur, &tmo, sendertag, argv 1, &rectype, NULL); if (rc != VCOM_RC_SUCCESS) { printf("dsconr failed, rc = %dn", rc); exit(1); } maxlen = sizeof(data); while (1) { dsrecv(&rc, &dsid, &maxlen, &len, data); if (rc == VCOM_RC_DB_EOF) break; if (rc != VCOM_RC_SUCCESS) { printf("dsrecv failed, rc = %dn", rc); break; } printf("Received data: '%s'n", data); } rvalue = VCOM_RC_SUCCESS; dsrlse(&rc, &dsid, &rvalue); }

Appendix A. Program examples

123

A.4
A.4.1

REXX program
Conversation initiator

/*** REXX *****************************************************/ /* */ /* FUNCTION : Send a request using VCOM */ /* */ /* SYNTAX : Call UDBSEND(data) */ /* */ /* ARGUMENTS : data */ /* */ /* OPTIONS : No options */ /* */ /* INPUT : See arguments. */ /* */ /* OUTPUT : udb_data */ /* */ /* RC : 0 - All is OK. */ /* 4 - No contact with VCOM */ /* 8 - Initialization failed */ /* */ /* NOTE : */ /* */ /* USERS : All Dept */ /* */ /* RESPONSIBLE : VCOM department */ /* */ /* AUTHOR : Name */ /* N.N */ /* */ /**************************************************************/ /*--EJECT-----------------------------------------------------*/ /* do not change */ /* M A I N - L O G I C */ /*------------------------------------------------------------*/ Arg udbrequest Address Ispexec /*-- Use if many ISPEXEC-calls --*/ Call A_INIT /*-- Initialize --*/ If rcode = 0 Then Do Call B_SEND /*-- Send the request --*/ End Call Z_FINIT /*-- clean up --*/

124

VCOMPGM

/*------------------------------------------------------------*/ /* E N D O F M A I N - L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B - R O U T I N E S */ /*------------------------------------------------------------*/ /*------------------------------------------------------------*/ /* A _ I N I T */ /* Initiate arg parms etc. */ /*------------------------------------------------------------*/ A_INIT: "CONTROL ERRORS RETURN " Signal On SYNTAX prefix tout secur partner init rcode = = = = = "VCOM_" "60" "UDB" "REXTST1" "UDB"

= 0

apirc = VCOMINI() If apirc /= 0 Then Do say "Initialization failed, rc " apirc rcode = 8 End Return

Appendix A. Program examples

125

/*--EJECT-----------------------------------------------------*/ /* B _ S E N D */ /*------------------------------------------------------------*/ B_SEND: apirc = CSCONS(vcomwork,prefix,secur,tout,,partner) If apirc = 0 Then Do say "Conversation established,id " VCOM_convid say "Request:" say udbrequest csid = VCOM_convid apirc = CSSEND(vcomwork,prefix,csid,,udbrequest) If apirc = 0 Then Do apirc = CSRECV(vcomwork,prefix,csid,tout) If apirc = 0 Then Do udb_data = VCOM_data say "Received answer:" say udb_data End Else Do say "Receive from VCOM failed, rc " apirc End End Else Do say "Send to VCOM failed, rc " apirc End apirc = CSRLSE(vcomwork,prefix,csid) End Else Do say "Connect to VCOM failed, rc " apirc rcode = 4 End Return /*--EJECT-----------------------------------------------------*/ /* add code if needed */ /* Z _ F I N I T */ /* */ /*------------------------------------------------------------*/ Z_FINIT: /* add more code here */ apirc = VCOMFIN(vcomwork) Exit rcode

/**************************************************************/ /************** End of exec ***********************************/ /**************************************************************/

126

VCOMPGM

A.4.2

Conversation responder

/*** REXX *****************************************************/ /* */ /* FUNCTION : Receive a request using VCOM */ /* */ /* SYNTAX : Call UDBRECV */ /* */ /* ARGUMENTS : none */ /* */ /* OPTIONS : No options */ /* */ /* INPUT : See arguments. */ /* */ /* OUTPUT : none */ /* */ /* RC : 0 - All is OK. */ /* 4 - No contact with VCOM */ /* 8 - Initialization failed */ /* */ /* NOTE : */ /* */ /* USERS : All Dept */ /* */ /* RESPONSIBLE : VCOM department */ /* */ /* AUTHOR : Name */ /* N.N */ /* */ /**************************************************************/ /*--EJECT-----------------------------------------------------*/ /* do not change */ /* M A I N - L O G I C */ /*------------------------------------------------------------*/ Arg udbrequest Address Ispexec /*-- Use if many ISPEXEC-calls --*/ Call A_INIT /*-- Initialize --*/ If rcode = 0 Then Do Call B_RECV /*-- Send the request --*/ End Call Z_FINIT /*-- clean up --*/

Appendix A. Program examples

127

/*------------------------------------------------------------*/ /* E N D O F M A I N - L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B - R O U T I N E S */ /*------------------------------------------------------------*/ /*------------------------------------------------------------*/ /* A _ I N I T */ /* Initiate arg parms etc. */ /*------------------------------------------------------------*/ A_INIT: prefix tout secur expediter answer rcode = = = = = "VCOM_" "60" "UDB" "REXTST1" "Answer on quetion about user"

= 0

apirc = VCOMINI() If apirc /= 0 Then Do say "Initialization failed, rc " apirc rcode = 8 End Return

128

VCOMPGM

/*--EJECT-----------------------------------------------------*/ /* B _ R E C V */ /*------------------------------------------------------------*/ B_RECV: apirc = CSCONR(vcomwork,prefix,secur,tout,expediter) If apirc = 0 Then Do say "Conversation established,id " VCOM_convid say "Initiator " VCOM_initiator say "Sendertag " VCOM_sendertag csid = VCOM_convid apirc = CSRECV(vcomwork,prefix,csid,tout) If apirc = 0 Then Do say "Received request:" say VCOM_data apirc = CSSEND(vcomwork,prefix,csid,,answer) If apirc = 0 Then Do say "Returned answer:" say answer End Else Do say "Send of answer to VCOM failed, rc " apirc End End Else Do say "Receive of request from VCOM failed, rc " apirc End apirc = CSRLSE(vcomwork,prefix,csid) End Else Do say "Connect to VCOM failed, rc " apirc rcode = 4 End Return /*--EJECT-----------------------------------------------------*/ /* add code if needed */ /* Z _ F I N I T */ /* */ /*------------------------------------------------------------*/ Z_FINIT: /* add more code here */ apirc = VCOMFIN(vcomwork) Exit rcode

/**************************************************************/ /************** End of exec ***********************************/ /**************************************************************/

Appendix A. Program examples

129

A.4.3

Distribution initiator

/*** REXX *****************************************************/ /* */ /* FUNCTION : Send a VCOM distribution */ /* */ /* SYNTAX : Call DISTSEND */ /* */ /* ARGUMENTS : data */ /* */ /* OPTIONS : No options */ /* */ /* INPUT : See arguments. */ /* */ /* OUTPUT : udb_data */ /* */ /* RC : 0 - All is OK. */ /* 4 - No contact with VCOM */ /* 8 - Initialization failed */ /* */ /* NOTE : */ /* */ /* USERS : All Dept */ /* */ /* RESPONSIBLE : VCOM department */ /* */ /* AUTHOR : Name */ /* N.N */ /* */ /**************************************************************/ /*--EJECT-----------------------------------------------------*/ /* do not change */ /* M A I N - L O G I C */ /*------------------------------------------------------------*/ Arg udbrequest Address Ispexec /*-- Use if many ISPEXEC-calls --*/ Call A_INIT /*-- Initialize --*/ If rcode = 0 Then Do Call B_SEND /*-- Send the request --*/ End Call Z_FINIT /*-- clean up --*/

130

VCOMPGM

/*------------------------------------------------------------*/ /* E N D O F M A I N - L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B - R O U T I N E S */ /*------------------------------------------------------------*/ /*------------------------------------------------------------*/ /* A _ I N I T */ /* Initiate arg parms etc. */ /*------------------------------------------------------------*/ A_INIT: "CONTROL ERRORS RETURN " Signal On SYNTAX prefix = tout = secur = partner = init = udbrequest rcode "VCOM_" "60" "UDB" "VT1MAD1" "UDB" = "test data"

= 0

apirc = VCOMINI() If apirc /= 0 Then Do say "Initialization failed, rc " apirc rcode = 8 End Return

Appendix A. Program examples

131

/*--EJECT-----------------------------------------------------*/ /* B _ S E N D */ /*------------------------------------------------------------*/ B_SEND: apirc = DSCONS(vcomwork,prefix,secur,tout,,partner) If apirc = 0 Then Do say "Distribution established,id " VCOM_distid dsid = VCOM_distid apirc = DSSEND(vcomwork,prefix,dsid,,udbrequest) If apirc = 0 Then Do say "Distribution ended OK" rvalue = "1" apirc = DSRLSE(vcomwork,prefix,dsid,rvalue) End Else Do say "Send to VCOM failed, rc " apirc rvalue = "0" apirc = DSRLSE(vcomwork,prefix,dsid,rvalue) End End Else Do say "Connect to VCOM failed, rc " apirc rcode = 4 End Return /*--EJECT-----------------------------------------------------*/ /* add code if needed */ /* Z _ F I N I T */ /* */ /*------------------------------------------------------------*/ Z_FINIT: /* add more code here */ apirc = VCOMFIN(vcomwork) Exit rcode

/**************************************************************/ /************** End of exec ***********************************/ /**************************************************************/

132

VCOMPGM

A.4.4

Distribution responder

/*** REXX *****************************************************/ /* */ /* FUNCTION : Receive a VCOM distribution */ /* */ /* SYNTAX : Call DISTRECV */ /* */ /* ARGUMENTS : data */ /* */ /* OPTIONS : No options */ /* */ /* INPUT : See arguments. */ /* */ /* OUTPUT : udb_data */ /* */ /* RC : 0 - All is OK. */ /* 4 - No contact with VCOM */ /* 8 - Initialization failed */ /* */ /* NOTE : */ /* */ /* USERS : All Dept */ /* */ /* RESPONSIBLE : VCOM department */ /* */ /* AUTHOR : Name */ /* N.N */ /* */ /**************************************************************/ /*--EJECT-----------------------------------------------------*/ /* do not change */ /* M A I N - L O G I C */ /*------------------------------------------------------------*/ Address Ispexec /*-- Use if many ISPEXEC-calls --*/ Call A_INIT /*-- Initialize --*/ If rcode = 0 Then Do Call B_RECV /*-- Send the request --*/ End Call Z_FINIT /*-- clean up --*/

Appendix A. Program examples

133

/*------------------------------------------------------------*/ /* E N D O F M A I N - L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B - R O U T I N E S */ /*------------------------------------------------------------*/ /*------------------------------------------------------------*/ /* A _ I N I T */ /* Initiate arg parms etc. */ /*------------------------------------------------------------*/ A_INIT: "CONTROL ERRORS RETURN " Signal On SYNTAX prefix = tout = secur = expediter= init = maxlth = rcode "VCOM_" "60" "UDB" "VT1MAD1" "UDB" "80"

= 0

apirc = VCOMINI() If apirc /= 0 Then Do say "Initialization failed, rc " apirc rcode = 8 End Return

134

VCOMPGM

/*--EJECT-----------------------------------------------------*/ /* B _ R E C V */ /*------------------------------------------------------------*/ B_RECV: apirc = DSCONR(vcomwork,prefix,secur,tout,expediter) If apirc = 0 Then Do say "Distribution established,id " VCOM_distid dsid = VCOM_distid apirc = DSRECV(vcomwork,prefix,dsid,maxlth) If apirc = 0 Then Do say "Data received: " VCOM_data rvalue = "0" apirc = DSRLSE(vcomwork,prefix,dsid,rvalue) End Else Do say "Receive from VCOM failed, rc " apirc rvalue = "0" apirc = DSRLSE(vcomwork,prefix,dsid,rvalue) End End Else Do say "Connect to VCOM failed, rc " apirc rcode = 4 End Return /*--EJECT-----------------------------------------------------*/ /* add code if needed */ /* Z _ F I N I T */ /* */ /*------------------------------------------------------------*/ Z_FINIT: /* add more code here */ apirc = VCOMFIN(vcomwork) Exit rcode

/**************************************************************/ /************** End of exec ***********************************/ /**************************************************************/

Appendix A. Program examples

135

A.5
A.5.1

Assembler program
Conversation initiator

*********************************************************************** * FUNCTION...: TEST OF CONVERSATION SERVICES IN VCOM. * * DIALER IN VD2. * * THIS PROGRAM CONNECTS AS A DIALER, SENDS THE MESSAGE * * VCOM CONVERSATION TEST: FROM PARTNER VT1MAC1 * * RECEIVES THE FOLLOWING ANSWER * * VCOM CONVERSATION TEST: FROM EXPEDITER VT1MAC1 * *********************************************************************** * PRINT NOGEN *

136

VCOMPGM

*********************************************************************** * * * MAINLINE * * * *********************************************************************** * * CONVSEND INIT CONVSEND,EQU=YES * TPUT CSMSG1,L'CSMSG1 * MESSAGE TO OPER * LOAD EP=CSCONS LR R15,R0 CALL (15),(VCRC,VCSID,VCSECUR, * CONNECT X VCTIMOUT,VCSNDTAG,VCPART,VCINIT),VL * BAL R14,CSRCCODE * CHECK RETURNCODE IF LTR,R15,R15,E * IF OK CONTINUE * MVC VCDATA,CSHELLO * DATA TO SEND * LOAD EP=CSSEND LR R15,R0 CALL (15),(VCRC,VCSID,VCLENGTH, * SEND X VCDATA),VL * BAL R14,CSRCCODE * CHECK RET CODE * MVC VCDATA,CSBLANK * BLANK DATA BUFF * LOAD EP=CSRECV LR R15,R0 CALL (15),(VCRC,VCSID,VCTIMOUT, * RECEVIE X VCMAXL,VCACTL,VCDATA),VL * BAL R14,CSRCCODE * CHECK RET CODE * IF LTR,R15,R15,E * IF RET OK TPUT VCDATA,L'VCDATA * DISPLAY DATA ENDIF * LOAD EP=CSRLSE LR R15,R0 CALL (15),(VCRC,VCSID),VL * RELEASE CONNECT * BAL R14,CSRCCODE * CHECK RET CODE ENDIF * FINIT CONVSEND *

Appendix A. Program examples

137

*********************************************************************** * * * SUBROUTINES * * * *********************************************************************** * * CSRCCODE SUB * IF CLC,VCRC,=XL4'00',E * RET CODE OK TPUT CSMSG2,L'CSMSG2 * MESS TO OPER L R15,=F'0' * RETURN OK ELSE * ELSE LH R2,VCRC * CONVERT HEX STC R2,CSRC+3 * TO ZONED SRL R2,4 * DECIMAL BUT STC R2,CSRC+2 * KEEP HEX SRL R2,4 * VALUE STC R2,CSRC+1 SRL R2,4 STC R2,CSRC MVZ CSRC,CSZONE * MOVE ZONE MVC CSMSG3+14(4),CSRC * MOVE RC TO MESS LH R2,VCRC * CONVERT HEX TO CVD R2,CSRCPACK * DECIMAL UNPK CSRCDEC,CSRCPACK MVZ CSRCDEC+14(1),CSRCDEC * FIX ZONE MVC CSMSG3+25(4),CSRCDEC+11 * MOVE RC TO MESS TPUT CSMSG3,L'CSMSG3 * DISPLAY RC L R15,=F'4' * RETURN NOT OK ENDIF * SUBEXIT * *

138

VCOMPGM

*********************************************************************** * * * WORKAREA * * * *********************************************************************** * *********************************************************************** * MESSAGES * *********************************************************************** CSMSG1 DC CL80'VCOM CONVERSATION SERVICE TEST' CSMSG2 DC CL80'RETURN CODE: 0000 HEX 0000 DEC' CSMSG3 DC CL80'RETURN CODE: HEX DEC' * *********************************************************************** * LOCAL VARIABELS * *********************************************************************** CSHELLO DC CL80'VCOM CONVERSATION TEST: FROM PARTNER VT1MAC1' CSBLANK DC CL80' ' * BLANK CSRC DS CL4 * RETURN CODE HEX CSZONE DC X'F0F0F0F0' * ZONE DS 0D CSRCPACK DC PL8'0' * RC PACKED CSRCDEC DS CL15 * RC DECIMAL * *********************************************************************** * VCOM PARAMETER AREA * *********************************************************************** DS 0D VCOMAREA DC XL176'00' * PAR AREA VCOM ORG VCOMAREA VCRC DS H * RETURNVALUE VCSID DC CL48' ' * SESSION ID VCSECUR DC H'4' * SECURITY INFO DC CL4'MATS' VCTIMOUT DC F'60' * TIMEOUT VALUE VCSNDTAG DC CL20'HELLO' * SENDERTAG VCPART DC CL8'VT1MAC1' * PARTNER ID VCEXP DS CL8 * EXPEDITER ID VCINIT DS CL8 * INITIATOR ID VCDATA DS CL80 * USER DATA S/R VCLENGTH DC F'80' * LENGTH OF DATA VCMAXL DC F'80' * MAX LENGTH DATA VCACTL DS XL4 * ACTUAL LEN DATA * LTORG END

Appendix A. Program examples

139

A.5.2

Conversation responder

*********************************************************************** * FUNCTION...: TEST OF CONVERSATION SERVICES IN VCOM. * * THIS PROGRAM CONNECTS AS AN RESPONDER, RECEIVES A * * MESSAGE AND THEN RETURN THE FOLLOWING ANSWER: * * VCOM CONVERSATION TEST: FROM EXPIDITER XXXXXXXX * * ALL VCOM COMMANDS AND RETURNCODES ARE WRITTEN TO THE * * SYSOUT FILE. THE RECEIVED MESSAGE IS ALSO WRITTEN * * TO THE SYSOUT FILE. * *********************************************************************** * PRINT NOGEN *

140

VCOMPGM

*********************************************************************** * * * MAINLINE * * * *********************************************************************** * CONVRECV INIT CONVRECV,EQU=YES * OPEN (CRSYSOUT,OUTPUT) * OPEN SYSOUT FILE * MVC CROUT(80),CRMSG1 * START MESSAGE PUT CRSYSOUT,CROUT * LOAD EP=CSCONR LR R15,R0 CALL (15),(VCRC,VCSID,VCSECUR, * CONNECT AS RESP X VCTIMOUT,VCSNDTAG,VCEXP,VCINIT),VL * MVC CROUT(11),=C'SENDERTAG: ' * SENDERTAG MVC CROUT+11(20),VCSNDTAG * SENDERTAG MSG PUT CRSYSOUT,CROUT * BAL R14,CRRCCODE * CHECK RC * IF LTR,R15,R15,E * IF OK CONTINUE * MVC VCDATA,CRBLANK * BLANK DATA BUFF * LOAD EP=CSRECV LR R15,R0 CALL (15),(VCRC,VCSID,VCTIMOUT, * RECEVIE X VCMAXL,VCACTL,VCDATA),VL * BAL R14,CRRCCODE * CHECK RC * IF LTR,R15,R15,E * IF RC OK MVC CROUT(80),VCDATA * DISPLAY DATA PUT CRSYSOUT,CROUT ENDIF * MVC VCDATA,CRHELLO * DATA TO SEND * LOAD EP=CSSEND LR R15,R0 CALL (15),(VCRC,VCSID,VCLENGTH, * SEND X VCDATA),VL * BAL R14,CRRCCODE * CHECK RC * LOAD EP=CSRLSE LR R15,R0 CALL (15),(VCRC,VCSID),VL * RELEASE * BAL R14,CRRCCODE * CHECK RC ENDIF * FINIT CONVRECV

Appendix A. Program examples

141

*********************************************************************** * * * SUBROUTINES * * * *********************************************************************** * * CRRCCODE SUB * IF CLC,VCRC,=XL4'00',E * RC OK MVC CROUT(80),CRMSG2 * RC OK MSG PUT CRSYSOUT,CROUT L R15,=F'0' * RETURN OK ELSE * ELSE LH R2,VCRC * CONVERT HEX CVD R2,CRRCPACK * TO DECIMAL UNPK CRRCDEC,CRRCPACK MVZ CRRCDEC+14(1),CRRCDEC * FIX ZONE MVC CRMSG3+14(4),CRRCDEC+11 * MOVE RC TO MSG MVC CROUT(80),CRMSG3 * RC NOT OK MSG PUT CRSYSOUT,CROUT L R15,=F'4' * RETURN NOT OK ENDIF * SUBEXIT * *********************************************************************** * * * EXECUTES * * * *********************************************************************** * * MOVE MVC 0(*-*,R4),2(R2) *

142

VCOMPGM

*********************************************************************** * * * WORKAREA * * * *********************************************************************** * *********************************************************************** * MESSAGES * *********************************************************************** CRMSG1 DC CL80'VCOM CONVERSATION SERVICE TEST' CRMSG2 DC CL80'RETURN CODE: 0000 DEC' CRMSG3 DC CL80'RETURN CODE: DEC' CRMSG10 DC CL80' ' * *********************************************************************** * LOCAL VARIABELS * *********************************************************************** CRHELLO DC CL80'VCOM CONVERSATION TEST: FROM EXPEDITER VT1MAD1' CRBLANK DC CL80' ' * BLANK CROUT DC CL132' ' * OUTRECORD DS 0D CRRCPACK DC PL8'0' * RC PACKED CRRCDEC DS CL15 * RC DECIMAL * *********************************************************************** * VCOM PARAMETER AREA * *********************************************************************** DS 0D VCOMAREA DC XL176'00' * PAR AREA VCOM ORG VCOMAREA VCRC DS H * RETURNVALUE VCSID DC CL34' ' * SESSION ID VCSECUR DC H'4' * SECURITY INFO DC CL4'MATS' VCTIMOUT DC F'60' * TIMEOUT VALUE VCSNDTAG DS CL20 * SENDERTAG VCPART DC CL8' ' * PARTNER ID VCEXP DC CL8'VT1MAC1' * EXPEDITER ID VCINIT DC CL8' ' * INITIATOR ID VCDATA DS CL80 * USER DATA S/R VCLENGTH DC F'80' * LENGTH OF DATA VCMAXL DC F'80' * MAX LENGTH DATA VCACTL DS XL4 * ACTUAL LEN DATA * *********************************************************************** * DCB'S * *********************************************************************** CRSYSOUT DCB DDNAME=OUTDATA,DSORG=PS,MACRF=PM,LRECL=132,RECFM=FB LTORG END

Appendix A. Program examples

143

A.5.3

Distribution initiator

*********************************************************************** * FUNCTION...: SAMPLE DISTRIBUTION PROGRAM. * * THE PROGRAM CONNECTS TO VCOM AND SENDS ONE RECORD * * AND THEN DISCONNECTS. * *********************************************************************** * PRINT NOGEN * *********************************************************************** * * * MAINLINE * * * *********************************************************************** * * DISTSEND INIT DISTSEND,EQU=YES * TPUT DSMSG1,L'DSMSG1 * MESSAGE TO OPER * LOAD EP=DSCONS LR R15,R0 CALL (15),(VCRC,VCSID,VCSECUR, * CONNECT X VCTIMOUT,VCSNDTAG,VCPART, X VCRECEIP,VCPRIO,VCINIT),VL * BAL R14,DSRCCODE * CHECK RETURNCODE IF LTR,R15,R15,E * IF OK CONTINUE * MVC VCDATA,DSHELLO * DATA TO SEND * LOAD EP=DSSEND LR R15,R0 CALL (15),(VCRC,VCSID,VCLENGTH, * SEND X VCDATA),VL * BAL R14,DSRCCODE * CHECK RET CODE * LOAD EP=DSRLSE LR R15,R0 CALL (15),(VCRC,VCSID,VCRVALUE),VL * RELEASE CONNECT * BAL R14,DSRCCODE * CHECK RET CODE ENDIF * FINIT DISTSEND

144

VCOMPGM

*********************************************************************** * * * SUBROUTINES * * * *********************************************************************** * * DSRCCODE SUB * IF CLC,VCRC,=XL4'00',E * RET CODE OK TPUT DSMSG2,L'DSMSG2 * MESS TO OPER L R15,=F'0' * RETURN OK ELSE * ELSE LH R2,VCRC * CONVERT HEX STC R2,DSRC+3 * TO ZONED SRL R2,4 * DECIMAL BUT STC R2,DSRC+2 * KEEP HEX SRL R2,4 * VALUE STC R2,DSRC+1 SRL R2,4 STC R2,DSRC MVZ DSRC,DSZONE * MOVE ZONE MVC DSMSG3+14(4),DSRC * MOVE RC TO MESS LH R2,VCRC * CONVERT HEX TO CVD R2,DSRCPACK * DECIMAL UNPK DSRCDEC,DSRCPACK MVZ DSRCDEC+14(1),DSRCDEC * FIX ZONE MVC DSMSG3+25(4),DSRCDEC+11 * MOVE RC TO MESS TPUT DSMSG3,L'DSMSG3 * DISPLAY RC L R15,=F'4' * RETURN NOT OK ENDIF * SUBEXIT * *

Appendix A. Program examples

145

*********************************************************************** * * * WORKAREA * * * *********************************************************************** * *********************************************************************** * MESSAGES * *********************************************************************** DSMSG1 DC CL80'VCOM DISTRIBUTION SERVICE TEST' DSMSG2 DC CL80'RETURN CODE: 0000 HEX 0000 DEC' DSMSG3 DC CL80'RETURN CODE: HEX DEC' * *********************************************************************** * LOCAL VARIABELS * *********************************************************************** DSHELLO DC CL80'VCOM DISTRIBUTION TEST: FROM PARTNER' DSBLANK DC CL80' ' * BLANK DSRC DS CL4 * RETURN CODE HEX DSZONE DC X'F0F0F0F0' * ZONE DS 0D DSRCPACK DC PL8'0' * RC PACKED DSRCDEC DS CL15 * RC DECIMAL * *********************************************************************** * VCOM PARAMETER AREA * *********************************************************************** DS 0D VCOMAREA DC XL256'00' * PAR AREA VCOM ORG VCOMAREA VCRC DS H * RETURNVALUE VCSID DC CL34' ' * SESSION ID VCSECUR DC H'0' * SECURITY INFO * DC CL4'MATS' VCTIMOUT DC F'60' * TIMEOUT VALUE VCSNDTAG DC CL20'HELLO' * SENDERTAG VCPART DC CL8'VT1MAD1' * PARTNER ID VCEXP DS CL8 * EXPEDITER ID VCINIT DS CL8 * INITIATOR ID VCRECTYP DS CL1 * RECEIVE TYPE DS 0H VCRECEIP DS 0CL75 * RECEIPT INFO VCRECID DS CL34 * DIST ID VCRCPART DC CL8' ' * PARTNER DC H'01' * RC DC H'0' * LENGTH VCPRIO DC CL1'N' * DIST PRIORITY VCDATA DS CL80 * USER DATA S/R VCLENGTH DC F'80' * LENGTH OF DATA VCMAXL DC F'80' * MAX LENGTH DATA VCACTL DS XL4 * ACTUAL LEN DATA VCRVALUE DC XL2'01' * RETURN VALUE * LTORG END

146

VCOMPGM

A.5.4

Distribution responder

*********************************************************************** * FUNCTION...: TEST OF DISTRIBUTION SERVICES IN VCOM. * * THIS PROGRAM CONNECTS AS AN RESPONDER, RECEIVES A * * DISTRIBUTION AND DELETES THE DISTRIBUTION. * * AFTER RECEIVING A DISTRIBUTION IT TESTS * * IF THERE ARE MORE DISTRIBUTIONS WITHIN VCOM * *********************************************************************** * PRINT NOGEN *

Appendix A. Program examples

147

*********************************************************************** * * * MAINLINE * * * *********************************************************************** * DISTRECV INIT DISTRECV,EQU=YES * OPEN (DRSYSOUT,OUTPUT) * OPEN SYSOUT FILE * DOWHILE CLC,VCRC,=XL2'00',E * UNTIL NO DIST * MVC DROUT(80),DRMSG1 * MESSAGE TO OPER PUT DRSYSOUT,DROUT * MVC DROUT,DRBLANK MVC VCSID,DRBLANK LOAD EP=DSCONR LR R15,R0 CALL (15),(VCRC,VCSID,VCSECUR, * CONNECT X VCTIMOUT,VCSNDTAG,VCEXP,VCRECTYP,VCINIT),VL * MVC DROUT(8),=C'DISTID: ' * DISTID MVC DROUT+8(34),VCSID * MESSAGE TO OPER PUT DRSYSOUT,DROUT MVC DROUT,DRBLANK MVC DROUT(11),=C'SENDERTAG: ' * SENDERTAG MVC DROUT+11(20),VCSNDTAG * MESSAGE TO OPER PUT DRSYSOUT,DROUT BAL R14,DRRCCODE * CHECK RC IF LTR,R15,R15,E * IF OK CONTINUE * DOWHILE CLC,VCRC,=XL2'00',E * UNTIL END * MVC VCDATA,DRBLANK * CLS DAT BUF * LOAD EP=DSRECV LR R15,R0 CALL (15),(VCRC,VCSID, * RECEVIE X VCMAXL,VCACTL,VCDATA),VL * BAL R14,DRRCCODE * CHECK RC * ENDDO * LOAD EP=DSRLSE LR R15,R0 CALL (15),(VCRC,VCSID,VCRVALUE),VL * RELEASE * BAL R14,DRRCCODE * CHECK RC ENDIF * MVC DROUT(80),DRMSG2 * MESSAGE TO OPER PUT DRSYSOUT,DROUT * ENDDO FINIT DISTRECV

148

VCOMPGM

*********************************************************************** * * * SUBROUTINES * * * *********************************************************************** * * DRRCCODE SUB * IF CLC,VCRC,=XL2'00',E * RET CODE OK L R15,=F'0' * RETURN OK ELSE * ELSE LH R2,VCRC * CONVERT HEX STC R2,DRRC+3 * TO ZONED SRL R2,4 * DECIMAL BUT STC R2,DRRC+2 * KEEP HEX SRL R2,4 * VALUE STC R2,DRRC+1 SRL R2,4 STC R2,DRRC MVZ DRRC,DRZONE * MOVE ZONE MVC DRMSG3+14(4),DRRC * MOVE RC TO MESS LH R2,VCRC * CONVERT HEX CVD R2,DRRCPACK * TO DECIMAL UNPK DRRCDEC,DRRCPACK MVZ DRRCDEC+14(1),DRRCDEC * FIX ZONE MVC DRMSG3+25(4),DRRCDEC+11 * MOVE RC TO MESS MVC DROUT(80),DRMSG3 * MESS TO OPER PUT DRSYSOUT,DROUT L R15,=F'4' * RETURN NOT OK ENDIF * SUBEXIT * *********************************************************************** * * * EXECUTES * * * *********************************************************************** * * MOVE MVC 0(*-*,R4),2(R2) *

Appendix A. Program examples

149

*********************************************************************** * * * WORKAREA * * * *********************************************************************** * *********************************************************************** * MESSAGES * *********************************************************************** DRMSG1 DC CL80'START DISTRIBUTION' DRMSG2 DC CL80'END DISTRIBUTION' DRMSG3 DC CL80'RETURN CODE: HEX DEC' * *********************************************************************** * LOCAL VARIABELS * *********************************************************************** DRBLANK DC CL80' ' * BLANK DRRC DS CL4 * RETURN CODE HEX DRZONE DC X'F0F0F0F0' * ZONE DROUT DC CL132' ' * OUTRECORD DS 0D DRRCPACK DC PL8'0' * RC PACKED DRRCDEC DS CL15 * RC DECIMAL * *********************************************************************** * VCOM PARAMETER AREA * *********************************************************************** DS 0D VCOMAREA DC XL256'00' * PAR AREA VCOM ORG VCOMAREA VCRC DC XL2'00' * RETURNVALUE VCSID DC CL34' ' * SESSION ID VCSECUR DC H'0' * SECURITY INFO VCTIMOUT DC F'0' * TIMEOUT VALUE VCSNDTAG DS CL20 * SENDERTAG VCPART DC CL8' ' * PARTNER ID VCEXP DC CL8'VT1MAD1' * EXPEDITER ID VCINIT DC CL8' ' * INITIATOR ID VCRECTYP DS CL1 * RECEIVE TYPE VCPRIO DS CL1 * DIST PRIORITY VCDATA DS CL150 * USER DATA S/R VCLENGTH DC F'150' * LENGTH OF DATA VCMAXL DC F'150' * MAX LENGTH DATA VCACTL DS XL4 * ACTUAL LEN DATA VCRVALUE DC XL2'0' * RETURN VALUE * *********************************************************************** * DCB'S * *********************************************************************** DRSYSOUT DCB DDNAME=OUTDATA,DSORG=PS,MACRF=PM,LRECL=132,RECFM=FB LTORG END

150

VCOMPGM

A.6

CICS Cobol program

ID DIVISION. PROGRAM-ID. CICSCOB AUTHOR. MATS ANDERSSON DATE-WRITTEN. MARS 1993 SKIP2 *REMARKS. * *---------------------------------------------------------* * SAMPLE DISTRIBUTION PROGRAM * * * * THE PROGRAM RECEIVES A DISTRIBUTION. * * * *---------------------------------------------------------* * ENVIRONMENT DIVISION. CONFIGURATION SECTION. OBJECT-COMPUTER IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. O1 FILLER PIC X(14)

VALUE '***VC14 PWS***'.

COPY DSCONR REPLACING ==:TAG:== BY ==DSCONR==. COPY DSRECV REPLACING ==:TAG:== BY ==DSRECV==. COPY DSRLSE REPLACING ==:TAG:== BY ==DSRLSE==.

Appendix A. Program examples

151

PROCEDURE DIVISION. MAIN SECTION. A100. MOVE ... . . MOVE 55 TO DSCONR-TIMEOUT. . . MOVE 'name' TO DSCONR-EXPEDITER. EXEC CICS LINK PROGRAM('DSCONR') COMMAREA(DSCONR) LENGTH(178) END-EXEC. MOVE DSCONR.DISTID . . MOVE ... TO DSRECV-DISTID.

PERFORM UNTIL DSRECV-RC <> 0 EXEC CICS LINK PROGRAM('DSRECV') COMMAREA(DSRECV) LENGTH(54) END-EXEC. END-PERFORM. MOVE DSCONR.DISTID TO DSRLSE-DISTID. MOVE 1 TO DSRLSE-RVALUE. EXEC CICS LINK PROGRAM('DSRLSE') COMMAREA(DSRLSE) LENGTH(38) END-EXEC. A999. GOBACK.

152

VCOMPGM

A.7

CICS IDEAL program

<<MAIN>> PROCEDURE MOVE 10 TO W-IDCSCONS.SECURLENGTH MOVE ' ' TO W-IDCSCONS.SECURDATA MOVE 55 TO W-IDCSCONS.TIMEOUT MOVE 'VC26 ' TO W-IDCSCONS.PARTNER CALL IDCSCONS USING W-IDCSCONS.IDCSCONSX MOVE IDCSCONS.CONVID TO W-IDCSSEND.CONVID MOVE 100 TO W-IDCSSEND.LENGTH MOVE 'CSSEND FROM IDEAL' TO W-IDCSSEND.DATA CALL IDCSSEND USING W-IDCSSEND.IDCSSENDX MOVE IDCSCONS.CONVID TO W-IDCSRECV.CONVID MOVE 55 TO W-IDCSRECV.TIMEOUT MOVE 100 TO W-IDCSRECV.MAXLENGTH CALL IDCSRECV USING W-IDCSRECV.IDCSRECVX MOVE IDCSCONS.CONVID TO W-IDCSRLSE.CONVID CALL IDCSRLSE USING W-IDCSRLSE.IDCSRLSEX MOVE MOVE MOVE MOVE MOVE MOVE IDCSCONS.RC IDCSCONS.CONVID IDCSCONS.PARTNER IDCSSEND.RC IDCSSEND.DATA IDCSRECV.RC TO TO TO TO TO TO TESTVC1.CRC TESTVC1.CONVID TESTVC1.PARTNER TESTVC1.SRC TESTVC1.DATA TESTVC1.RRC

declarations of copy texts: ----- ------------------ - - ----- ----- ----------------LEVEL FIELD NAME T I CH/DG OCCUR VALUE/COMMENTS ----- ------------------ - - ----- ----- ----------------1 W-IDDSCONR COPY DVW IDCSCONR 1 W-IDDSCONS COPY DVW IDCSCONS 1 W-IDDSRECV COPY DVW IDCSRECV 1 W-IDDSSEND COPY DVW IDCSSEND 1 W-IDDSRLSE COPY DVW IDCSRLSE

Appendix A. Program examples

153

154

VCOMPGM

Index
A
API parameter description 43 API verb description 48 Application protocol 24, 31 Application protocol - Question/Answer protocol 1 31 Application protocol - Question/Answer protocol 2 32 Assembler 72 Assembler program 136 Conversation initiator 136 Conversation responder 140 Distribution initiator 144 Distribution responder 147 Confirm 25 Conversation initiator 92, 114, 120, 124, 136 Conversation responder 97, 116, 121, 127, 140 Conversation services 23 Application protocol 31 Data header 28 Error handling 29 Fetch connect parameters 27 printable data 30 Copy text 35, 74, 82 CSCONR verb 52 CSCONS verb 50 CSRECV verb 55 CSRLSE verb 57 CSSEND verb 54

B
Batch 88

D
Data header 14, 28 Definitions 24 Application protocol 24 Flip-Flop protocol 24 Half-Duplex protocol 24 Listener 24 More data 26 Record 26 Speaker 24 Transaction 24 Transaction types 25 Demand 25 Distribution initiator 102, 118, 122, 130, 144 Distribution responder 108, 119, 123, 133, 147 Distribution services 13 Data header 14 Error handling 21 Fetch connect parameters 13 printable data 22 Receipt handling 22 Sequence of VCOM and DB calls 16 DSCONR verb 61
Index 155

C
C 38 C program 120 Conversation initiator 120 Conversation responder 121 Distribution initiator 122 Distribution responder 123 CICS 86 CICS Cobol program 151 CICS IDEAL program 153 Cobol 34, 73 Copy text 35, 74 Dynamic subprograms 35 Parameter passing 34, 73 Cobol program 92 Conversation initiator 92 Conversation responder 97 Distribution initiator 102 Distribution responder 108 Coding IMS transactions 87 Common problems 89

DSCONS verb 58 DSPRLS verb 71 DSRCNS verb 69 DSRECV verb 65 DSRLSE verb 67 DSSEND verb 63 Dynamic subprograms

L
Language 33 Listener 24 Lock 25 35

M E
Environment 85 Error 25 Error handling 21, 29 Examples 91 Methods 13 Methods for Conversation services 23 Methods for distribution services 13 More data 26

O F
Fetch connect parameters 13, 27 Flip-Flop protocol 24 Fortran 37 Fortran program 114 Conversation initiator 114 Conversation responder 116 Distribution initiator 118 Distribution responder 119 Operation environment 85

P
Parallell CICS transactions. 86 Parameter description 43 Parameter passing 34, 37, 38, 72, 73, 81 Parameter passing 37, 38, 72 printable data 22, 30 Program examples 91 Protocol 24

H
Half-Duplex protocol 24

Q
Query 25

I
IDEAL for CICS 81 Copy text 82 Parameter passing 81 IMS 87 IMS generation 87 IMS requirements 87 IMS Subpool 87 IMS transaction coding 87 Include files 38 Include files 38 Interface code 37, 42 Interface code 37, 42

R
Receipt 59, 66 Receipt handling 22 Record 26 Reject 25 Request 25 REXX 43 REXX program 124 Conversation initiator 124 Conversation responder 127 Distribution initiator 130 Distribution responder 133

156

VCOMPGM

S
Sequence of VCOM and DB calls Speaker 24 Started task 88 Subprograms 35 16

V
VCOM verbs 48 CSCONR verb 52 CSCONS verb 50 CSRECV verb 55 CSRLSE verb 57 CSSEND verb 54 DSCONR verb 61 DSCONS verb 58 DSPRLS verb 71 DSRCNS verb 69 DSRECV verb 65 DSRLSE verb 67 DSSEND verb 63 VCOMFIN verb 49 VCOMINI verb 49 VCOMFIN verb 49 VCOMINI verb 49 Verbs 48 CSCONR verb 52 CSCONS verb 50 CSRECV verb 55 CSRLSE verb 57 CSSEND verb 54 DSCONR verb 61 DSCONS verb 58 DSPRLS verb 71 DSRCNS verb 69 DSRECV verb 65 DSRLSE verb 67 DSSEND verb 63 VCOMFIN verb 49 VCOMINI verb 49

T
Transaction 24 Transaction types Confirm 25 Demand 25 Error 25 Lock 25 Query 25 Reject 25 Request 25 Unlock 25 TSO 88 25

U
Unlock 25

Index

157