You are on page 1of 157

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 Mölndal 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

3

4 VCOMPGM .

. 2. . . . . . . . . . . . . . . . . . . . . . . .8 More data . . . . . . . . . . . . . . . . .2 Distribution with few records . . . . . . . . . .2. . . . . . . . . . Contents 5 . . . . . . . . . . . . . .5 Printable data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Application protocol . . . .4 REXX . . . . . . . . . . . . . . . . . . . .6. . . . .1 Calling sequence . . . . . 2. . . . . .2 Copy text . . . . . .1. . . . . . . . 2. . 2.3 API verb description . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . .1 Distribution services . . . . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . .1. . . . . . . . . . . .3. . . . . . .2. . . .1 Parameter passing . . . . . . . . . .1. . . . . . .3 Sequence of VCOM and DB calls . . . . . . . 2. . . . . . . . . . . . . . .2 Data header . . . . . . . . . . .1 Parameter passing .2. . . . . . . .2. . . 2. . . . . . 2. . . . . . .2. .0 Language . . . .1. . . . . .1. . . . . . . . . . . 2.5 Transaction .2 Interface code . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .0 Introduction . . . . . . . . 3. 3. . . .4. . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . . . . . . . . . . . . . . . . 2. . .6. . . . . . . . .4. . . .4 Listener . . . . . . . . . . . . . . . . .Question/Answer protocol 2 3. . . . . . . . . . .4 Error handling . 2. . . . . . .6 Application protocol . . . . . . . . . 2. . . . . . . 2. . .1 Parameter passing . . . . . . . . . . . . . . .2. . . .2. . . 2. . . . . . . . . . . . . . . . . . . . . 3. . . . 3. . . . . . .2.3 Data header . . . . . . . . . .1. .3 C . . . . . . . . . . . 2. . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Receipt handling . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . .1 Cobol . . . . . . . . . . . . . . . 2. . . . . . . . . . . . . . . . . 3. . . . . . 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . 9 . . . . . . . . . . . . . 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. .2 Application protocol . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . .1 Application protocol . . . . . . . . . . . . . 3. . . . . . . . . . .2. . . . . . . . . . . . . . .1.1 Definitions . . . . . . . . . . . .1. . . . . . . . . . . 2. . . . . . . . . . . . . . . . 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. . . . . . . . . . . . . . . . . .5 Printable data . . . . . . . . . . . . . . . . . . . .1.1 Distribution with many records . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. . . . . . 2. . . . . . . . . . . . . . . . .2. . . . . .2 Fortran . .2 Conversation services . . .2 Half-Duplex Flip-Flop protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . . .3 Interface code . . . . . . . . . . . . . . 3. . .4 Return codes . . . . . . . . . . . . . . . . . . . . . .3 Speaker . . . . . . 2. . . . . . . . . . . . . . . .4 Error handling . . . . . . . . . . . . . .6 Transaction types . . . . . . . . .1 Parameter passing . . .4. . . . 2. . . . . . . . . . .2. . . . . . . . 3. . . . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. . . . 3. . .7 Record . . . . . . . . . . . . 3. . . . . . 2. . . . . . . . . . . . . . . . . . . . . . . . . . . .Contents 1. . . . . . . . . . .2. . . . . . . . . . . . . . . . . . 2. . . . . . . . . . . . . . 2. .1. . .1. . . . . . . . . . . . . . . . . .2 Parameter description 3. . . . . . . . . . . . 2. . . . . . . . . . . . 3. . . 3. . . . . . . . . . .2 Fetch connect parameters . . . . . . . . . . . . . . . . .2 Include files . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . .0 Methods .1. . . . . . . .Question/Answer protocol 1 2. . . . . .2. . .1 Fetch connect parameters .1. .1. . . . . . . . . . . . . . . .1. . . . .1. . . . . . . . . .2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . . .1. . . . . . . . . . . .2 Two-phase commit . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . .3 Dynamic subprograms 3. . . . . . . .

. . . . . . .1. . . . . . . . . . . . . . . . .3 Distribution initiator . . . . . . . . . . .5. . . . . . . . . . . .2. . . . . .6. . . . . . .3.1 Conversation initiator . 3.6 Started task . . . . . . . . . . . . . . . . .2 Conversation responder A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Conversation initiator . . . . . .0 Common problems . . . . . . . . . . .4 Distribution responder . . . . .4. . . .. . . . . . . . . . . . . . . . . . . . 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . . . . .1. .2. . . . . .. . . . . . . . . . . . . .. . . . . .2 Conversation responder A. . . . . . . . . . . . . . . . .3 Distribution initiator . .. . .4. . . . . . . . . . . . . . . . . . . .4 Distribution responder . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. . . . . . . . . . . . . . . . . .2.11 DSCONS . . . . . . . . . . . . . . . . . 89 . . . . . . . . . . . . . . . . . . . . . . . .4. . . .4. . . . ..4 Distribution responder .4. . . . . . . . . . . .3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .3 Distribution initiator . . . . . .6. . . . . .. . . . . ..5. . . . . . . . .2 CICS . . . . A. . . A. . . . . .5. . . . A. . . . 3. . . . . A. . . . . . . . . . . . . . . . . . . .. . . .. . . . . . . .. . . . . . . . . . . . . . .1 Parameter passing 3.17 DSPRLS . . . 5. . . . .4. . .. . .. . .. . . . . . . . . . 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.2 Conversation responder A. . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .7. . . . . . . . . . .16 DSRCNS . . .7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . .4. . 90 .. . . . . . . . . . . . . . . . .. . .3. . . . . . . A. . . . . 3. . . . . . . . . . . . . . . . 3. . .1 Parameter passing 3. . .. .3. . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . .. . . . . . . . .5 TSO . . . . . . . . . .6 Cobol for CICS .. . . .10 CSRLSE . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . .8 CSSEND .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . .14 DSRECV . . A. A. . .2. . . . . . . . .3 Distribution initiator . . . A. . .7 CSCONR . . . . . . . . . A. . . . . . . . Program examples A. . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . .. . . . . . . . . . . . . . . . . . . . . . A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . .1 Operation environment . . 4. . . . . . . . . . . . . . . . . . . A. .3 IMS . . . . . . .1 Conversation initiator . . . . . . . . . . . . .4. . . . . . . . . . . . .2 Copy text . . . . . .4 REXX program . . . . . . . . . .. . . . . . . . . . . . . .2 Conversation responder A. . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . . . . . . 3. . . .. . . . .2 Conversation responder A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 CSRECV . . . . . 6 VCOMPGM . . . . . . .4 Batch .1 Parameter passing 3. . .4 Distribution responder . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A. . . . . . . . . . . . . . . . . . . . .. . . . . . .6 CSCONS . 3.5 Assembler program . . . .5. . . 3. .12 DSCONR . . . . . . . . . . . . . . . .13 DSSEND . . . . .5 Assembler . . . . . . . . . . . . . . .5. 90 . . . . . . . . . . . . . . . . . . . . . . . . . . A. . . . . . . ... . . . . . . . . .. . . . . . A. . . A. .2 Fortran program . . . . . . . . . . . . . . . . . A. . . . . . . . . . 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. . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . . . .1. . . . . . . . . . . . . . . .. 4. . . . . . . . . . . . . . . . . . . . . .4 Distribution responder . . . . . . .. . . . .15 DSRLSE . . . . . . . . . . . . . . A. . . . . . . . . . . . . . . . . . . . . 3. . . A.. . . . . . . . . .. . . . . . . 3. . . . . . . . . . . . . . . . .5. . . . . . . . 3. . . . . . . . . . . . . . . . . . .0 Environment .3 Distribution initiator . A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . .. . . . .4. . . . . 3. . . . . . . . . . . . . . . . . . . . .4. . . . . . . . .4. . . . . . . . . . . . . . . . .2. . . . . . . . . . . 3. . .. . .. . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Conversation initiator . . . .2 VCOMFIN . . 3. . . . . . . . .4. . . . . . . . . .2 Copy text . . . . .4. . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Cobol program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Parallell transactions 4. . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . 4. . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . .1 VCOMINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . .7 IDEAL for CICS . . . . .3 C program . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . .4. . . . . . . . . . 87 . . . . . . .5 Initialisation . . . . . . . . . .5. . . . . . . . . . . . . . . . . . . . . . . . . . .1 Conversation initiator .. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 CICS IDEAL program . 153 Contents 7 . . . . . . . . . . . 151 Index .A. . . . . . . . . . . . . . . . .7 CICS Cobol program . . . . . . . . . . . .6 A. . . .

8 VCOMPGM .

. .. . ... . Program logic for initiating program . . . Program logic for responder . error handling . . . .. . .... printable data . . 4. 18. .. 11. . . fetch connect parameters . .. . 9. . . .. .. . . . . . . Reconnect logic for initiator . . . . . 5. . . . . . . . .. receipt handling . . 22. Distribution methods. . sequence of VCOM and DB Call sequence . . .. . application protocol . . . . .. . . Conversation methods. . . Coding of IMS/VCOM transaction.. . . . Distribution methods. . Distribution with few records . 21. 17.. One question .. . . . Several questions .. . . . . .. . . . . . . 13. .. . .. . ... . . . . . 10. . . . 20. Conversation data layout . . . . ... . . . . . . . . . . . . . . . .. . Application protocol.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. . . . . .. . 8.. . fetch connect parameters Conversation methods. . . . 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 9 .. .. . . . . Distribution methods. Distribution methods. . . . . .... . . . . .. . . . . . .. . . . .... . . . . 7. . Distribution methods. . . . Application protocol.. .. . . Conversation methods. . Proram for enabling parallell CICS transasction . . .. .. error handling . Distribution with many records . . . Conversation methods. . .. . 16. . . . . . 3. . 15. . 6. data header . . Conversation methods. . . Distribution methods... . . . . . . . . .. .. . . . . .. .... . .. . . . . . .. . . calls . 19.. data header . . .. . .. . . . . . . .. . .. .. . . . . 2. .... . . . 12. . . printable data . . . . . . 14. . .

.

however.1. 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. IBM PC's. UNIX etc. also run in the same computer. The main purpose of VCOM is to provide services for program-to.program communication for distributed application systems. This programming interface is consistent across various computer environments. i. IBM mainframes. A distributed application system in this context is a system consisting of at least two programs.e. the cooperating programs would be geographically separated. they would run in different computers or environments. using VCOM as the tool for data transfer.0 Introduction VCOM is designed to provide a common interface to data communications for application system development. Normally.e. DEC machines. Introduction 11 . They may. co-operating in order to perform a function. The manual is also intended to form a complement to the VCOM API manual. i. IBM midrange (AS/400).

12 VCOMPGM .

2. Distribution methods. for more information see the VCOM API manual.1 Distribution services The following paragraph will discuss various matters concerning the VCOM distribution services (VCOM/DS). VCOM will work well in many other ways than the ones described in this section.1 Fetch connect parameters +--------------------------+ ! ! ! fetch connect parameters ! ! ! +--------------------------+ Figure 1. there may very well be occasions where other methods are wanted.1.0 Methods This section contains a description of methods used with VCOM. needed or better suited. Many of the subjects described are common for both conversation and distribution services but are discussed separately. 2. Methods for both VCOM conversations and distributions are discussed. Even though some recommendations are given in this chapter. The subjects covered are: • • • • • • Connect parameters Data headers Sequence of VCOM and DB calls Error handling Character sets and printable data Receipt handling 2. VCOM distributions are used to send messages between two applications in an asynchronous way. fetch connect parameters Methods 13 .

2 Data header +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! ! +--------------------------+ Figure 2. The key can for instance be program name or subject etc.It is recommended that the connect parameters are stored in 'application database'. like application names.g: time-out values). a key into that table must be defined to be able to identify the parameters to use. Another criteria is the kind of information needed to be transmitted together with the data. The reason for this is to • • allow increased flexibility. The data can be formatted in many different ways depending on application needs. data header The data sent between the two programs must be understood by both ends . 14 VCOMPGM . parameter library or another suitable place and can be read at connect time. This fact indicates that the layout and structure of the data is important. One criteria to decide how this should be done is the number of records sent. message type etc.1. Distribution methods. 2. increase the tuning possibilities (e. 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.

The following records should to start with a record type if records of different type exist in the distribution.One general recommendation.2. . this can easily be handled by the two applications (truncating and padding) but the data can still be sent with a variable length. . however. . The first record in the distribution would then include control information about subject. application names. program name etc. Using variable length records will reduce transfer time and processing costs. is only to send vital data. 2. Methods 15 . VCOM/DS uses variable length records (the record length is specified for each record). Distribution with many records When there are many records in one distribution logically connected.1. . If the data sent need to be of a fixed length on both sides.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 ! ! ! ! ! ! ! +------------------------------------------------------+ . the recommendation is to group them together. Figure 3.

. Figure 4..3 Sequence of VCOM and DB calls +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! ! +--------------------------+ Figure 5. 16 VCOMPGM .2.1.2 Distribution with few records Subject From appl To appl From program Record type +----------------------------------------------------------------+ ! ! ! ! ! ! ! ! ! ORDER ! PROST ! AKOS ! VGK010 ! ORDER head ! 120034 ! . . 2.! ! ! ! ! ! ! ! ! +----------------------------------------------------------------+ . 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. 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. Distribution methods. Actions to take: • The amount of data in one distribution ought to be the same as for the database transaction. This to make the processing easier.1. . This makes it possible to rollback the distribution and transaction.2.

• Commit towards the database should be done before DSRLSE towards VCOM. the distribution is put back on the distribution queue (retaining its position) if the application is ended abnormally before DSRLSE.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. Call sequence If a database transaction fails. If the distribution (application data) is only written to a file.e deleted if it is the initiating side and put back on the distribution queue on the responding side. . • Conditions to consider: • When sending a distribution. this should result in a rollback of the distribution i. . When receiving a distribution. +----------------------+ ! Commit ! +----------------------+ VCOM +----------------------+ ! DSCONS / DSCONR ! +----------------------+ +----------------------+ ! DSSEND / DSRECV ! +----------------------+ +----------------------+ ! DSRLSE normal ! +----------------------+ +----------------------+ ! Rollback ! +----------------------+ +----------------------+ ! DSRLSE Rollback ! +----------------------+ Figure 6. Methods 17 . this file should be closed before the DSRLSE verb is issued. Database actions like Update. In case of an error it is possible to make a Roll-Back (delete) of the distribution.1. • 2.3. Insert and Delete correspond to the DSSEND and DSRECV verbs and finally the Commit/Rollback correspond to DSRLSE (normal or rollback). all information about the distribution is deleted if the application is ended abnormally before DSRLSE or DSPRLSE. Database +----------------------+ ! Start transaction ! +----------------------+ +----------------------+ ! Update/Insert/Delete ! +----------------------+ .

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

.search criteria..) Retrieve data to send from the database While (data to send) Call DSSEND (rc..search criteria.. The following need to be considered: Methods 19 .) Save distribution id COMMIT If (Commit = OK) Call DSRLSE (normal) Else Call DSRLSE (rollback) Endif Figure 7... Call DSRCNS (rc. Depending on the outcome of the commit the DSRLSE can be either normal or rollback..) Enddo Figure 8. DSPRLS is made before the commit and with the DSPRLS verb VCOM will save the distribution and wait for the DSRLSE verb...) Update database Retrieve more data to send Enddo Call DSPRLS (rc. 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...Start transaction Call DSCONS (rc.. In this way. • 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. 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.. Whether to include the re-connect logic in the initiating program or to implement a supervising program depends upon a number of factors.) 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. 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.. The verb can be used by the initiating program itself or it is possible to develop a general supervising program..

• If the distribution id is found.) 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...... The distribution is in this case already processed and the only thing left is to perform a DSRLSE normal. 20 VCOMPGM .) Enddo Save distribution id in application database COMMIT If (Commit = OK) Call DSRLSE (normal) Else Call DSRLSE (rollback) Endif Endif Call DSCONR (rc. 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. Sequence control. • The program was interrupted the last time this distribution was processed.. Figure 9 on page 18 shows the logic for a responding program. this indicates that the database was updated and that the distribution should be released (normal)... the distribution id is used to look in the application database to see if it already has been processed or not. Supervising strategy.• • • • Performance of the initiating program. • If the distribution id is not found in the application database. The fact that the distribution id exists indicates that the updates in the database have been made.. If the distribution id is not found this indicates that the database was not updated and that the distribution should be deleted (rollback). If the distribution id is found in the application database. Call DSCONR (rc.. it is an indication that the following has occurred. Program logic for responder When the program starts to receive a distribution (DSCONR).) Enddo Figure 9.. one of the two following events may have occurred.

Refer to the 'Language chapter' in this manual. When using these return codes in the program it is better to use symbolic names instead. the application should exit the VCOM distribution in a way that is agreed for this specific case. It is suggested that these return codes are grouped together. The return code and the VCOM identity parameters Methods 21 . What return codes/events should result in the program performing an EXIT (ends). Most of the return codes are not very likely to be issued. supplied in cobol copytexts or C include files etc. 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. The most common action after a return code test is of the type 'EXIT'. This section does not describe the symbolic names for the return codes. error handling Proper error handling is always important. The catagorization below is an example. Return codes that indicate that the the program should try again (for instance different types of time-out's). also when using VCOM. When these types of return codes occur.4 Error handling +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! ! +--------------------------+ Figure 10. Matters that need to be considered are: • • What return codes the program should handle. VCOM uses return codes with 4 bytes. Distribution methods. Category Normal Try again Try later Exit Description Normal return codes that the application should handle (for instance 'No more records').1. 2.• The distribution has not been processed before (this is the normal case).

Distribution methods. VCOM also has the ability to transfer data as binary.6 Receipt handling 22 VCOMPGM . VCOM can only translate characters that are represented in ISO 8859-1 (ISO-latin-1) and the character sets used by the applications.1. Note: It is not possible to mix binary and translation mode within one distribution. 2. printable data VCOM can do character translation on request. For this reason the recommendation is only to use 'printable data' when transferring text that should be understood by both programs. 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. partner. No translation is then performed by VCOM.1.5 Printable data +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! ! +--------------------------+ Figure 11. A translation error occurs when a character does not exist in both user character sets and in ISO 8859-1.(distribution id.

+--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! +--------------------------+ +-! ! ! receipt handling ! ! ! +--------------------------+ Figure 12.2 Conversation services This section will discuss various matters concerning the VCOM conversation services (VCOM/CS). In VCOM.. the application developers need to decide how the result of the distribution ought to be verified. In some cases (when it is necessary). 2. this can be accomplished in several ways: • • • • Use VCOM receipt handling. for more information see the VCOM API manual. . Distribution methods.. A decision also has to be made whether there always should be some kind of verification or only when an error has occurred. Send a ordinary distribution as verification. the data is always transferred to the other application if no timeout value for the distribution has been specified. receipt handling When using VCOM distribution services. The subjects covered are: • • Definitions Connect parameters Methods 23 . This is usually insufficient for as verification that the data has been delivered and that the result was correct. VCOM conversations are used to send messages between two applications in a synchronous way. Use sequence number in the distributions so that later distributions can verify previous distributions.

1 Application protocol A set of rules.5 Transaction A 'processable' unit transmitted in one direction from current speaker to current listener.1. The programs cannot have the same role at the same time.4 Listener The program without the authority to speak (CSSEND) is the current listener (CSRECV). 2.2.1.2. The speaker/listener role can be alternated during the connection according to the application protocol. The definitions made here are not included in the VCOM specification but.1 Definitions When using VCOM/CS.2. 2.2. a terminology like this is needed.1.2 Half-Duplex Flip-Flop protocol Programs using VCOM conversation services exchange data using a Half-Duplex Flip-Flop protocol.1.2. The transaction transmission is normally followed by some kind of computer processing by the listener. The initiator program is normally the first speaker but does not have to be. 2.1. Basically this means that only one application at a time can send data. One of the advantages with VCOM is that it uses a common terminology across the different computer platforms. 2. This is defined in the application protocol.• • • • Data headers Error handling Character sets and printable data Application protocol 2.3 Speaker The program with has the authority to speak (CSSEND) is the current speaker. 2. The programs cannot have the same role at the same time. the terminology may need to be expanded. The speaker/listener 24 VCOMPGM . The speaker/listener role can be alternated during the connection according to the application protocol.2. which define the data flow and what kind of processing is expected between two connected application programs.

The main reason for introducing the error transaction is to give a possibility to inform the other side that the protocol has been violated. Confirm: Normal response to a Lock. No negotiation is possible. Lock: A request from the current speaker to lock a database entry for later update. Transactions are divided into initiator transactions and response transactions according to the origin (initiator/responder).1. 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. An Order Change Demand (forced update) is a typical example. A transaction can consist of one or more records defined according to the application processing and reply requirements. A Request should always be replied by a Confirm or Reject transaction. see “More data” on page 24) or as an own transaction. The speaker should perform error handling procedures. Demand or Query transaction. Request: A Request from the current speaker for remote data base update at the listener site. Demand: A Demand from the current speaker for remote database update at the listener site. An Order Change Request is a typical example.6 Transaction types Within an application area. abort the transaction Methods 25 . Query: In this case the current speaker is requesting remote data base retrieve only. Demand or Query transaction. Reject Abnormal response to a Lock. The Query transaction should be responded to by a Confirm or Reject transaction depending on the result. The transaction is normally preceded by a confirmed lock. Request. The Demand transaction should be responded toby a Confirm transaction. Request. the following transaction types can be seen as examples depending on the kind of service requested (or demanded). Unlock: A request from the current speaker to unlock a previous locked data base entry. A Lock transaction should always be responded to by a Confirm or Reject transaction.role is normally alternated after the transmission of a transaction (half duplex flip/flop). 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. 2. 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.2. An Unlock transaction should always be responded toby a Confirm transaction. Unlock.

The Error transaction should not be used for unexpected VCOM return codes.in progress and disconnect when an error transaction is transmitted.2. 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.8 More data A means to control the record flow from speaker to listener and indicate the end of the transaction to the listener. 26 VCOMPGM . 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 contain a reason code and an error code.2.7 Record A 'protocol unit' included in a transaction. abort the transaction in progress and disconnect. The maximum number of records within a transaction needs to be specified in order to prevent application program buffer overflow from occuring. The listener should perform error handling procedures. The field should be included as a standard item in each record.1. 2. When last record is sent/received the speaker/listener role is alternated. 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.1. More data equals YES indicate that there are more records to be received. Records normally have some kind of structure and sort order within a transaction. More data equals NO means that this was the last record in the transaction.

2. 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 reason for this is to • • increase flexibility. increase the tuning possibilities (ex: time-out values). Conversation methods. parameter library or another suitable place and can be read at connect time.2. Methods 27 . The key can for instance be program name or subject etc.2 Fetch connect parameters +--------------------------+ ! ! ! fetch connect parameters ! ! ! +--------------------------+ Figure 13. fetch connect parameters It is recommended that the connect parameters are stored in an 'application database'.

2. Both network overhead and computer processing time/costs will be reduced if the number of interactions are reduced to a minimum. Conversation methods.3 Data header +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! ! +--------------------------+ Figure 14. Conversation data layout 28 VCOMPGM .. Transaction type ! ! More data indicator ! ! ! ! Subject From To From Record ! ! appl appl program type ! ! +-------------------------------------------------------------------+ ! ! ! ! ! ! ! ! ! ! !T!I! ORDER ! PROST ! AKOS ! VGK010 ! ORDER head ! 120034 ! .. There are several ways to design the structure of the data.2. but it is important (for performance reasons) to keep the number of CSSEND/CSRECV requests as few as possible. This fact indicates that the layout and structure of the data is important. data header The data that is sent between the two programs must be understood by both ends.! ! ! ! ! ! ! ! ! ! ! +-------------------------------------------------------------------+ Figure 15.

Most of the return codes are not very likely to be issued. Matters that need to be considered are: • • What return codes the program should handle. When these types of return codes occur. Category Normal Try again Try later Exit Description Normal return codes that the application should handle (for instance CSRLSE). Following symbolic return codes should at least be handled by the application: Return code Success CSRLSE Description Ok (Normal) CSRLSE received (Normal) Methods 29 . error handling Proper error handling is always important and is so also when using VCOM. Return codes that indicate that the the program should try again (for instance different types of time-out's). What return codes/events should result in the program performing an EXIT (ends). Refer to the 'Language chapter' in this manual. VCOM uses return codes with 4 bytes. 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.2. The return code and the VCOM identity parameters (distribution id.4 Error handling +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! ! +--------------------------+ Figure 16. expediter etc) should be logged for problem determination purposes.2. The catagorisation below is an example. When using these return codes in the program it is better to use symbolic names. Conversation methods. supplied in cobol copytexts or C include files. the application should exit the VCOM conversation in a way that is agreed for this specific case. This section does not describe the symbolic names for the return codes. It is suggested that these return codes are grouped together. partner. The most common action after a return code test is of the type 'EXIT'.

2. printable data VCOM can do character translation upon request. in which case VCOM does not perform any translation. 30 VCOMPGM .5 Printable data +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! ! +--------------------------+ Figure 17. a translation error will occur.Timeout Not availible Security error Timeout for DSCONS or DSCONR (Try again) VCOM not availible (Try later) Security data error (Exit) 2. VCOM can only translate characters that are represented in ISO 8859-1 (ISO-latin-1) and the charactersets used by the applications. Note: It is not possible to mix binary and translation mode within one conversation. 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. If a character does not exist in both user charactersets or in ISO 8859-1. Conversation methods.

One question Methods 31 . In Figure 19 on page 29. will only describe the data flow. This section.Question/Answer protocol 1 This type of protocol is used when there is always only one question within each conversation. Conversation methods.6. The question can result in several answers. 2. however.2.2. The protocols described here are of the type 'question/answer'.6 Application protocol +--------------------------+ ! ! ! fetch connect parameters ! ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! +--------------------------+ +-! ! ! application protocol ! ! ! +--------------------------+ Figure 18.2. Transaction types and error handling is described earlier in this chapter. 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.1 Application protocol . application protocol The application protocol set up between a pair of application programs control the dataflow. Connect (CSCONS) (CSSEND) Send Question loop until no more data to receive Receive Answer end loop Disconnect (CSRLSE) (CSRECV) Figure 19. Application protocol. specifies the data layout that is sent and what to do in error situations.

Several questions 32 VCOMPGM .2.Question/Answer protocol 2 This type of protocol is used when the conversation can include several questions. Application protocol.2 Application protocol . Each question can result in several answers. the logic may be seen from the initiating program's point of view.2.6. In Figure 20 on page 30. 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.

0 Language This section describes of how the VCOM verbs are coded for a specific language. Language 33 .3. 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.

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.1.3.1 3. Program examples” on page 89.1 Cobol Parameter passing All calls to VCOM are of the type 'called by reference'. 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

&sndtag.3.3. Program examples” on page 89. &tmo.3 3. &init). 38 VCOMPGM .2 Include files The include files below are delivered with the VCOM software. &prt.1 C Parameter passing All calls to VCOM is of the type 'called by reference'. More examples can be found in “Appendix A. &secur. 3. Example: cscons(&rc. &csid.3.

/* 16-bit integer typedef unsigned short VcomUInt16. If you're using an old K&R compiler. struct char }. typedef /* struct csid CSID. All clients should define this to hide/show all client specific definitions. The behavior of this file can be controlled by the following macros: WINDOWS WIN32 CLIENT NO_PROTO If you're building a Windows 3. */ */ */ */ */ */ */ */ struct char }. you must define WINDOWS to get the corrent prototypes. VCOM_H VCOM_H /* * Vcom return codes */ #include "rc.Conversation ID csid { id 34“. /* 32-bit integer typedef unsigned long VcomUInt32. define NO_PROTO. which doesn't support function prototypes. constants and function prototypes for the VCOM API. /* 32-bit integer typedef unsigned int VcomUInt32.h" /* * Machine-independent type definitions */ typedef short VcomInt16.Distribution ID dsid { id 34“. */ DSID . Must be defined if you're building a client under Windows 95 or Windows NT.h Data structures. /* 32-bit unsigned integer #endif /* CSID . Language 39 . /* 32-bit unsigned integer #else typedef long VcomInt32. typedef struct dsid DSID. /* 16-bit unsigned integer #ifdef __osf__ /* DecUnix has 64-bit long typedef int VcomInt32.x client./* * * * * * * * * * * * * * * * * * */ #ifndef #define vcom.

}.receipt on error */ /* > 0 -. /* Length of receipt data */ /* User data (if any) comes here */ }./* Structure to describe security info in connect calls */ struct secinfo { VcomInt16 usdlen. /* Receiving partner */ short rc. char usdata 99“. */ /* 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 .receipt always */ VcomInt16 len. typedef struct receipt RECEIPT. /* Original distid */ char partner 8“. /* Structure used to describe a receipt in DSCONS calls */ struct receipt { char dsid 34“. /* Return code: /* <= 0 -. typedef struct secinfo SECINFO.

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

dsconr().extern extern extern extern extern #ifdef extern extern extern extern #endif extern extern extern extern extern extern extern void void void void void cscons(). dsrecv(). dssend(). #ifndef CLIENT extern void _zvfundecl extern void _zvfundecl extern void _zvfundecl #endif #endif #endif /* NO_PROTO */ /* VCOM_H */ opercon(). CLIENT void void VcomInt16 void _zvfundecl _zvfundecl _zvfundecl _zvfundecl consrv().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. /* * * * * */ rc.h VCOM return codes #define VCOM_RC_SUCCESS #define #define #define #define 1 /* 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. operrls(). opercmd(). dsrcns(). 42 VCOMPGM . dmpvcom(). discsrv(). This is done by a very small module called VCOMLC that must be linked together with the application itself. dsrlse(). getvcomver(). csrecv(). dsprls(). csrlse().3. csconr(). void void void void void void void dscons(). the parameter list must be constructed in a certain way. cssend().

4.3. This means that the developer should not need to do any extra coding around the VCOM verbs when using them. Output arguments are returned in standard output variables. 3. The idea is that this interface should give the REXX programmer a way to use VCOM following the REXX calling conventions.2 Parameter description The following table describes the parameters used together with the VCOM API verbs. If the prefix is longer than 20 characters it will be truncated with no warning.4 REXX The REXX programming language differs in several ways from other programming languages such as Cobol. not addresses or pointers. These variables are defined after a call to VCOM has been performed.1 Parameter passing The arguments passed in the REXX verbs are only of type input. rc >= 1 char Language 43 . Return code. Value set by VCOM after a verb has completed.4. The data passed is always the data. The output variable names are built from a prefix concatenated with a specific output parameter name. prefixes output parameter names. 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. 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. Name prefix Type <= 20 characters Description Prefix name.

The parameter must either be specified by both sides or be omitted by both sides.536. This is the identification given by a responder to inform of the expediter name of the responding process. Text string. sendertag 0.20 characters partner 1. 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..8 characters Partner identification.99 characters Security information. both the initiator and the responder must specify the same information in order to have a connection established. Note that this parameter is translated by VCOM into the character code appropriate for the environment where the VCOM implementation is run.. The timeout value is specified in seconds and the maximum value that may be used is 365 days (corresponding to a value of 31. The conversation id or distribution id is assigned by VCOM after a connection has been established. timeout 1. The security information can be up to 99 characters long. session id sequence number (4 characters). session id time stamp in the format YYYYMMDDhhmmss (14 characters). The parameter can be used to exchange security information. The valid character set to use is VCOM character set.Name convid distid Type 34 characters Description Session id for a conversation or a distribution. secur 0. VCOM node name of initiator (8 characters). Expediter identification. Note that this parameter is translated by VCOM into the character code appropriate for the environment where the VCOM implementation is run.. expediter 1. The id is 34 characters and has the following structure: net node crtim seqnr VCOM network name of initiator (8 characters).8 characters 44 VCOMPGM .000 seconds). The sendertag is any string that the sender wishes to send to the receiver in the connect phase. The valid character set to use is VCOM character set... If the parameter is used.8 characters Timeout value.

One of the following values are used: D Data. (c)(r)length >= 0 character rvalue >= 1 character Return value. The receipt information has the following structure: distid partner rc length data id of the original distribution associated with the receipt. The maximum length is 9999 bytes. Used to indicate a normal data distribution. The priority assigned a distribution by its originator. receipt character string Receipt information. (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 receipt data (16 bits). This is the receipt data as specified by the originator of the associated distribution when the distribution was created. 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. prio 1 character Distribution priority. The receive type identifies the type of distribution that is going to be received by a distribution responder.Name rectype Type 1 character Description Receive type. Length of user data area to send or length of input area to be used for receive. the partner name of the recipient. Max length is 256 bytes. R Receipt. user receipt data. The receipt information is specified by the originator of a distribution when the distribution is created. return code for the distribution associated with the receipt. Length of user data area. One of the following values may be used: N normal distribution priority. Language 45 . Used to indicate a receipt distribution. E express distribution priority.

8 characters Description Initiator identification.. 46 VCOMPGM . This is the identification given by the primary side to indicate from whom a conversation request or a distribution request originates.Name Initiator Type 1.

Name vcomwork Type 4 characters Description Work code. The code must be passed in all following VCOM verbs. they are not prefixed by the prefix name. set by the VCOMINI verb.The following variables is set by the VCOM REXX api. character(s) The result code is set in the calling program if a verb is called as a subroutine. character(s) The return code is set in the calling program if a verb is called as a function. rc Language 47 . described earlier. result >= 1 Result value (return code). >= 1 Rc. return code.

the function call is replaced by the return code when returning to the application. If the VCOM verb was called as a function. After each parameter name is specified whether the parameter value is set by the application program or by VCOM.4 Return codes Return codes are transferred to the REXX environment in several ways. The notation o is used for output parameters set by VCOM after the verb has completed.3 API verb description The following pages describes each of the verbs provided by the VCOM REXX API.4. that is set by the api before it returns control to the application. If the VCOM verb was called as a subroutine. There is also a special VCOM variable 'RC'. 48 VCOMPGM . 3. Each verb description also includes the parameters specific to that verb.4. The notation i is used for input parameters set by the application program before the verb is issued.3. the return code is placed in the REXX special variable 'RESULT'. the way it's retuned depends on how the VCOM verb was called from the application. The 'RC' may be prefixed by the prefix parameter.

4. 3. the only thing you can do with it is to pass it to the api. The parameter is required.2 VCOMFIN Verb: Description: VCOMFIN (vcomwork) The verb is used to terminate an api session.5. The code is only for internal use.1 VCOMINI Verb: Description: VCOMINI () The verb is used to initiate an api session. The following output parameters are set by the REXX interface. 3. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. You are only allowed to perform this call once.5. This verb will declare and set a variable called 'vcomwork'. When you have performed your last CS/DS verb you should release the environment by calling 'VCOMFIN'. after your last CS or DS verb. This name must be passed in all verbs following the 'VCOMINI' verb. before your first CS or DS verb. Language 49 . The output names are not prefixed.5 Initialisation Added to the commonly used VCOM verbs are two verbs only used by the REXX api. The variable is four characters long and contains a binary value.4. The string is set by VCOM/API at the completion of the verb. You are only allowed to perform this call once.4. These verbs are provided to setup and remove an environment used by the REXX api only. Note: VCOMINI should be called only once at the beginning of a VCOM session. vcomwork (o) work code.3. VCOMFIN should be called only once at the end of a session. Before you are allowed to perform any CS or DS verbs you must do a VCOMINI call.

The parameter is a numeric string of 1 to 8 characters. initiator) The verb is used to initiate a conversation with a partner. This is only applicable between two partners in the same node. 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. The parameter is required. secur. 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 the default prefix will be 'VCOM'.4. The parameter is required. secur (i) security information. The maximum length is 20 characters. if passed. The maximum length of the string is 99 characters. timeout. timeout (i) timeout value in seconds. A positive value indicates the maximum time in seconds that the initiator is prepared to wait for the conversation to be established. The parameter is optional. prefix (i) Prefix name. partner. A negative value may be used to indicate that no timeout value is to be used. 50 VCOMPGM . The prefix is used to prefix the standard output names. if passed. 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. The parameter. should be a valid name.6 CSCONS Verb: Description: CSCONS (vcomwork. The parameter is optional. If the parameter is omitted or empty. i.e. the initiator is prepared to wait indefinitely for the conversation to be established. should be a text string. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. prefix.3. sendertag. The string passed should contain a numeric value.

The parameter is optional. The parameter is a string of 1 to 8 characters. This is the identification of the conversation and this id must be used in all subsequent verbs issued to the same conversation. The parameter is optional. The string is set by VCOM/API at the completion of the verb. The following output parameters are set by the REXX interface. The string is set by VCOM/API at the completion of the verb if the return code indicates that a conversation has been started. Language 51 . The parameter is used by the application program to identify the partner process from whom the connect request originates. convid (o) conversation id. The parameter is a string of 34 characters. partner (i) identification of the partner program.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 output names are prefixed by the prefix value passed through the verb. rc (o) return code. The parameter is a string of 1 to 8 characters. The string is used by the application program to identify the partner process to which a conversation is requested. The parameter is required. The variable is four characters long and contains numerics only. initiator (i) identification of the initiator program. The maximum length is 20 characters.

prefix. if passed. 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 parameter is a numeric string of 1 to 8 characters. secur (i) security information. If the parameter is omitted the default prefix will be 'VCOM'.e. the responder is prepared to wait indefinitely for a conversation request from a partner program. i. A positive value indicates the maximum time in seconds that the responder is prepared to wait for a conversation to be established. If the parameter is omitted or empty. The parameter is required. timeout. should be a text string. The parameter is optional. prefix (i) Prefix name.7 CSCONR Verb: Description: CSCONR (vcomwork.4. The prefix is used to prefix the standard output names. expediter) The verb is used to respond to a conversation request from a partner program. timeout (i) timeout value in seconds.3. A text string has to be given by the application program if a security check is to be made against the partner program. 52 VCOMPGM . 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 is optional. The parameter is required. secur. 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 maximum length of the string is 99 characters. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The string passed should contain a numeric value. A negative value may be used to indicate that no timeout value is to be used. The name can contain a maximum of 20 characters. The parameter. should be a valid name. if passed. The parameter.

The parameter is required. sendertag (o) sender information. initiator (o) identification of the initiator program. The variable is 0 to 20 characters long information text. The parameter is a string of 1 to 8 characters. This variable is set by VCOM/API at the completion of the verb. This string is used by the application program in order to identify to VCOM the name of the expediter that is starting. rc (o) return code. 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 output names are prefixed by the prefix value passed through the verb. convid (o) conversation id. The variable is set by the primary application program to identify the partner process from whom the connect request originates. 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 8 character long name.expediter (i) identification of the responding program. The following output parameters are set by the REXX interface. The parameter is a string of 34 characters. Language 53 . 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 four characters long and contains numerics only.

The parameter is optional and the default length is set to the length of the data string. rc (o) return code. This is the identification of the conversation on which the data is to be sent. The parameter is required. The variable is four characters long and contains numerics only. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. convid (i) conversation id.3. The maximum length differs between the different enviroments. The name can contain a maximum of 20 characters. length. User data that is to be sent on the conversation to the partner program.prefix. The parameter is required. data (i) user data.8 CSSEND Verb: Description: CSSEND (vcomwork . length (i) length information. The length parameter specifies the amount of data to send. The parameter. The output names are prefixed by the prefix value passed through the verb. convid. The prefix is used to prefix the standard output names. The parameter is an alphanumeric string. The parameter is required. data) The verb is used to send data on a conversation to a partner program. This field is set by VCOM/API at the completion of the verb. should be a valid name. The parameter is a numeric string of maximum 4 characters The parameter is optional. 54 VCOMPGM . prefix (i) Prefix name.4. The parameter is optional. The following output parameters are set by the REXX interface. If the parameter is omitted the default prefix will be 'VCOM'. The parameter is a string of 34 characters. if passed.

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

The parameter is optional. receipt. should be a valid name. 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.3. sendertag (i) sender information. If this parameter is omitted or empty.4. timeout (i) timeout value in seconds. timeout.11 DSCONS Verb: Description: DSCONS (vcomwork. The parameter is required. The data type is a 1 to 20 character long string. The parameter is a numeric string of 1 to 8 characters. The parameter is optional. The parameter contains any string of characters that the sender of the distribution wishes to send to the distribution recipient. The name can contain a maximum of 20 characters. The parameter. 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. sendertag. The parameter is set by the application program if a security check is to be made against the partner program. If the parameter is omitted the default prefix will be 'VCOM'. prio. prefix. secur. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. A negative value indicates that no timeout is associated with the distribution. prefix (i) Prefix name. if passed. partner. The prefix is used to prefix the standard output names. secur (i) security information. The value zero is not used. The parameter is a 0 to 99 bytes long alphanumeric string. The parameter is required. 58 VCOMPGM . The parameter is optional. initiator) The verb is used to initiate a distribution to a partner.

The parameter is 1 to 8 character long name. The parameter is a one byte character code. The receipt information is a structured text string. The parameter is a structured string described below. 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 1 to 8 character long name. partner (i) identification of the receipt partner program. prio (i) distribution priority. 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. The parameter is optional. Language 59 . receipt (i) receipt information. The field is set by the application program to identify the partner process to which the receipt shall be delivered. The parameter is set by the application program to identify the partner process from whom the distribution was delivered. The parameter is optional. 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 parameter is set by the application program to identify the partner process to which the distribution shall be delivered. The following values may be used: >0 <=0 indicates that the receipt always is to be delivered to the receipt recipient. The parameter specifies the requested priority for the distribution. 'normal' priority will be used by VCOM. The string contains the fields described below in that order. The parameter is optional and if omitted. The parameter is required. initiator (i) identification of the initiator program.partner (i) identification of the partner program. padded with blanks if the name is shorter than eight characters. The data type is a string of 8 bytes. The string can have a length between 13 and 269 characters depending on user data.

The type is an alphanumeric string. The parameter is a string of 34 characters. data (i) user data. This is the identification of the distribution and this id must be used in all subsequent verbs issued to the same distribution. distid (o) distribution id.The type is a numeric string of 5 bytes. The output names are prefixed by the prefix value passed through the verb. 60 VCOMPGM . rc (o) return code. This variable is set by VCOM/API at the completion of the verb. padded with zeroes if the number is shorter than five characters. User data to be included in the receipt. The following output parameters are set by the REXX interface. 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 variable is four characters long and contains numerics only.

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. expediter (i) identification of the responding program. the request will be completed with the return code VCOM_RC_NODISTR. prefix (i) Prefix name.4. timeout. The parameter is required. prefix. The parameter is optional. This parameter is set by the application program in order to identify to VCOM the name of the expediter that is starting. expediter) The verb is used by an application program to identify itself to VCOM as a distribution receiver. the responder is prepared to wait indefinitely for a distribution to arrive.3.e. If the parameter is omitted the default prefix will be 'VCOM'. Language 61 . 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. timeout (i) timeout value in seconds. The parameter. A negative value may be used to indicate that no timeout value is to be used. if passed. If no distribution is pending. secur (i) security information. The parameter is set by the application program if a security check is to be made against the partner program. secur. The parameter is optional. A positive value indicates the maximum time that the responder is prepared to wait for a distribution to arrive. The name can contain a maximum of 20 characters. should be a valid name. The parameter is a numeric string of 1 to 8 bytes. If this parameter is omitted or empty. i. The parameter is required. The parameter is a 0 to 99 characters long alphanumeric string.12 DSCONR Verb: Description: DSCONR (vcomwork. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter passed should contain a numeric value. The prefix is used to prefix the standard output names.

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

The parameter is required. The parameter is optional and the length will be set to the length of the data string by default. The parameter is a string of 34 characters. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. The parameter. distid (i) distribution id. The prefix is used to prefix the standard output names. prefix (i) Prefix name. The output names are prefixed by the prefix value passed through the verb. if passed. The parameter is required. The parameter is required. The data type is a character string. The length parameter specifies the amount of data to send. If the parameter is omitted the default prefix will be 'VCOM'. The following output parameters are set by the REXX interface. This is the identification of the distribution on which the data is to be sent. The parameter is optional. should be a valid name. Note that the data transfer is a local process between the application program and the local VCOM node. length (i) length information. prefix. This variable is set by VCOM/API at the completion of the verb. rc (o) return code.3. The maximum length differs between the different environments. The parameter is a numeric string of maximum 4 characters. The parameter is optional.4. distid.13 DSSEND Verb: Description: DSSEND (vcomwork. length. data) The verb is used to send data on a distribution to a partner program. data (i) user data. Language 63 . User data that is to be sent on the distribution to the partner program. The name can contain a maximum of 20 characters.

64 VCOMPGM .The variable is four characters long and contains numerics only.

The maximum length differs between the different environments. This is the identification of the distribution on which data is to be received. Language 65 . if passed. maxlength (i) maximum length. The parameter is a numeric string of maximum 4 characters. Note that the data transfer is a local process between the application program and the local VCOM node. The parameter is required. should be a valid name. The parameter is a string of 34 characters. distid (i) distribution id. The parameter. The variable is four characters long and contains numerics only. The name can contain a maximum of 20 characters. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. rc (o) return code. The output names are prefixed by the prefix value passed through the verb. If the parameter is omitted the default prefix will be 'VCOM'. prefix (i) Prefix name. If the parameter is omitted the length will be set to '9999'. maxlength) The verb is used to receive data in a distribution from a partner program or to receive a receipt distribution. actlength (o) actual length. This variable is set by VCOM/API at the completion of the verb.3.4. The parameter is optional. The parameter is optional. 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. distid. The maximum length parameter specifies the maximum amount of data that may be received in the data area. The following output parameters are set by the REXX interface. The prefix is used to prefix the standard output names.14 DSRECV Verb: Description: DSRECV (vcomwork. The parameter is required. prefix.

data (o) user data area. You can convert the binary return code by using the following two REXX instructions. User data area that is going to be used for reception of data in the distribution from a partner program.characters NOTE.characters the partner name of the recipient. rc_binary = SUBSTRING(data.characters id of the original distribution associated with the receipt. 2 . This is the receipt data as specified by the originator of the associated distribution when the distribution was created.2) rc = C2D(rc_binary.45. BINARY VALUE return code for the distribution associated with the receipt. partner rc The value is a structured string. 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. BINARY VALUE length of receipt data.43.2) data 0 to 256 characters User receipt data. The receipt structure can be seen below: distid 34 .2) length 2 . You can convert the binary length value by using the following two REXX instructions.The value is a numeric string.characters NOTE. length_b = SUBSTRING(data. 8 .2) length = C2D(length_b. 66 VCOMPGM .

e. rvalue (i) return value. the return code in the receipt will be updated with the rvalue and VCOM receipt processing will begin. if passed. the following values may be used: >=0 indicates that the distribution is accepted by the receiver. prefix (i) Prefix name. The parameter is a string of 34 characters.15 DSRLSE Verb: Description: DSRLSE (vcomwork. the distribution is to be forwarded by VCOM to its ultimate destination. If a receipt is associated with the distribution. 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. not 1 As a receiver. The name can contain a maximum of 20 characters. The parameter is optional. any other value than 1 indicates that the distribution is to be cancelled. it is strongly recom- Language 67 . The parameter is required.3. prefix. The parameter is required. distid. This is the identification of the distribution which is to be terminated. The parameter. the following values may be used: 1 indicates normal release of a distribution. The prefix is used to prefix the standard output names. To be able to see who is giving the return code (VCOM or the application). The return value specifies the termination condition when the release verb is issued by a distribution sender. If the parameter is omitted the default prefix will be 'VCOM'. i. As a sender. 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. distid (i) distribution id.4. should be a valid name.

rc (o) return code. If a receipt is associated with the distribution. indicates that the distribution is rejected and should be returned to VCOM and put in hold status. 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. can be either positive or negative why usually the absolute value rather than the signed value should be considered. 68 VCOMPGM . The next DSCONR will return the same distribution again.mended for the application to use 0. The output names are prefixed by the prefix value passed through the verb. <-999 indicates that the distribution is accepted by the receiver. The following output parameters are set by the REXX interface. Depending on enviroment the presentation of the receipt-rc. The parameter is required. -2 The parameter is a numeric string. The variable is four characters long and contains numerics only. -1 indicates that the distribution is rejected and should be returned to VCOM for restart. the return code in the receipt will be updated with the rvalue and VCOM receipt processing will begin. This range of rvalue can be used to indicate error situations to the receipt handling program. when receiving the receipt. Normal VCOM receipt processing is started when this value is used. This variable is set by VCOM/API at the completion of the verb. although the distribution is finished as far as VCOM is concerned.

This is the identification of the distribution. The parameter is set by the application program if a security check is to be made against the partner program. The parameter is used to search for distributions matching this partner. partner (i) identification of the partner program. The parameter is optional. distid. The parameter is 0 to 99 character long. Language 69 . If this parameter is omitted or empty. partner. 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.4. prefix. The prefix is used to prefix the standard output names. The parameter is optional. The parameter.16 DSRCNS Verb: Description: DSRCNS (vcomwork. The parameter is 1 to 8 character long. The name can contain a maximum of 20 characters. The only action that can be done to this distribution is a release (DSRLSE).3. The parameter is used to search for distributions matching this initiator. If the parameter is omitted the default prefix will be 'VCOM'. prefix (i) Prefix name. The parameter is optional. secur. To be able to do re-connect to a distribution a DSPRLS verb must have been issued to that distribution before it was interrupted. secur (i) security information. The parameter is a string of 34 characters. if passed. The following parameters are used: vcomwork (i) vcomwork is an environment code set by the VCOMINI verb. should be a valid name. initiator (i) identification of the initiating program. If a value is given this will be used to find that distribution. initiator) The verb is used to re-connect to an interrupted distribution at the primary side. The parameter is required. The parameter is optional. distid (i) distribution id. The parameter is 1 to 8 character long.

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

1 Cobol for CICS Parameter passing All calls to VCOM are executed using the LINK function. Program examples” on page 89. 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.6 3.6.3. Language 73 .

SPACE. SPACE. SPACE. SPACE. COMP PIC PIC COMP PIC PIC PIC PIC S9(4).6. There are two types of copy texts delivered. COMP PIC PIC COMP PIC PIC PIC PIC S9(4). S9(8) X(20) X(8) X(8) VALUE VALUE VALUE VALUE ZERO. 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. PIC X(34). PIC X(34).3. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-SECUR. CVCSCONS 01 CSCONS. 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:. SPACE. SPACE. S9(8) X(20) X(8) X(8) VALUE VALUE VALUE VALUE ZERO. 05 RC 05 CONVID 05 SECUR. X(99). One type uses a tag function. 74 VCOMPGM . 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT 05 :TAG:-SENDERTAG 05 :TAG:-PARTNER 05 :TAG:-INITIATOR COMP PIC S9(4).2 Copy text The copytexts below are delivered with the VCOM software. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 PARTNER 05 INITIATOR COMP PIC S9(4). X(99).

SPACE. VALUE SPACE. SPACE. X(34) VALUE SPACE. SPACE. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 EXPEDITER 05 INITIATOR COMP PIC S9(4). S9(8) X(20) X(8) X(8) VALUE VALUE VALUE VALUE ZERO. X(34). SPACE.CCSCONR 01 :TAG:. CVCSCONR 01 CSCONR. 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT 05 :TAG:-SENDERTAG 05 :TAG:-EXPEDITER 05 :TAG:-INITIATOR COMP PIC S9(4). X(99). COMP PIC PIC COMP PIC PIC PIC PIC S9(4). COMP PIC PIC COMP PIC PIC PIC PIC S9(4). PIC X(34). PIC X(34). X(9999). CCSSEND 01 :TAG:. VALUE ZERO. X(99). X(9999). 05 RC 05 CONVID 05 LENGTH 05 DATA COMP PIC PIC COMP PIC PIC S9(4). CVCSSEND 01 CSSEND. Language 75 . S9(8). S9(8) X(20) X(8) X(8) VALUE VALUE VALUE VALUE ZERO. SPACE. SPACE. 05 RC 05 CONVID 05 SECUR. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-LENGTH 05 :TAG:-DATA COMP PIC PIC COMP PIC PIC S9(4). S9(8) VALUE ZERO. 05 :TAG:-RC 05 :TAG:-CONVID 05 :TAG:-SECUR.

S9(8). CVCSRECV 01 CSRECV. 05 RC 05 CONVID COMP PIC S9(4). 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.CCSRECV 01 :TAG:. CCSRLSE 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. PIC X(34) VALUE SPACE. X(9999). 76 VCOMPGM . S9(8) VALUE ZERO. S9(8). S9(8) VALUE ZERO. S9(8) VALUE ZERO. S9(8) VALUE ZERO. PIC X(34) VALUE SPACE. 05 :TAG:-RC 05 :TAG:-CONVID COMP PIC S9(4). X(9999). CVCSRLSE 01 CSRLSE.

SPACE. X(34) VALUE SPACE. X(1) X(8) VALUE ZERO. X(256). X(1) VALUE "N". X(8) VALUE SPACE. S9(4) VALUE ZERO. S9(8) X(20) X(8) VALUE ZERO. VALUE VALUE VALUE VALUE SPACE. VALUE "N". PIC X(34). PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC S9(4). PIC X(34). 10 RECEIPTID 10 RECEIPTPARTNER 10 RECEIPTRC 10 RECEIPTLENGTH 10 RECEIPTDATA 05 PRIO 05 INITIATOR COMP PIC S9(4). X(99). VALUE SPACE. 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). VALUE SPACE. ZERO. VALUE SPACE. S9(4) VALUE ZERO. X(8) VALUE SPACE. CVDSCONS 01 DSCONS. ZERO. 05 RC 05 DISTID 05 SECUR. 10 :TAG:-SECURLENGTH COMP 10 :TAG:-SECURDATA 05 :TAG:-TIMEOUT COMP 05 :TAG:-SENDERTAG 05 :TAG:-PARTNER 05 :TAG:-RECEIPT. VALUE SPACE. COMP PIC PIC COMP PIC PIC PIC PIC PIC COMP PIC COMP PIC PIC PIC PIC S9(4). 05 :TAG:-RC COMP 05 :TAG:-DISTID 05 :TAG:-SECUR. X(99). VALUE SPACE. S9(8) X(20) X(8) X(34) X(8) S9(4) S9(4) X(256). 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 PARTNER 05 RECEIPT.CDSCONS 01 :TAG:. Language 77 .

05 RC 05 DISTID 05 LENGTH 05 DATA COMP PIC PIC COMP PIC PIC S9(4). 05 RC 05 DISTID 05 SECUR. X(34) VALUE SPACE. VALUE SPACE. S9(8) X(20) X(8) X(1). 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). 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-LENGTH 05 :TAG:-DATA COMP PIC PIC COMP PIC PIC S9(4). S9(8). X(34). VALUE SPACE. VALUE SPACE. VALUE SPACE. COMP PIC PIC COMP PIC PIC PIC PIC PIC S9(4). S9(8) VALUE ZERO.CDSCONR 01 :TAG:. COMP PIC PIC COMP PIC PIC PIC PIC PIC S9(4). X(9999). X(8) VALUE ZERO. VALUE SPACE. 10 SECURLENGTH 10 SECURDATA 05 TIMEOUT 05 SENDERTAG 05 EXPEDITER 05 RECTYPE 05 INITIATOR COMP PIC S9(4). CDSSEND 01 :TAG:. X(9999). PIC X(34). VALUE SPACE. PIC X(34). CVDSCONR 01 DSCONR. CVDSSEND 01 DSSEND. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-SECUR. VALUE ZERO. X(99). VALUE SPACE. 78 VCOMPGM . S9(8) X(20) X(8) X(1). X(99). X(8) VALUE ZERO.

05 RC 05 DISTID 05 SECUR. S9(8). S9(8) VALUE ZERO. CVDSRLSE 01 DSRLSE. 10 SECURLENGTH 10 SECURDATA 05 PARTNER 05 INITIATOR COMP PIC S9(4). X(9999). X(9999). PIC X(34). 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). PIC X(34). COMP PIC PIC PIC PIC S9(4). VALUE ZERO. 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-RVALUE COMP PIC S9(4). X(34) VALUE SPACE. X(99). 05 :TAG:-RC 05 :TAG:-DISTID 05 :TAG:-SECUR. PIC X(34) COMP PIC S9(4) VALUE SPACE. VALUE SPACE. 05 RC 05 DISTID 05 MAXLENGTH 05 ACTLENGTH 05 DATA COMP PIC PIC COMP PIC COMP PIC PIC S9(4). 05 RC 05 DISTID 05 RVALUE COMP PIC S9(4). Language 79 . PIC X(34) COMP PIC S9(4) VALUE SPACE.CDSRECV 01 :TAG:. CDSRLSE 01 :TAG:. X(99). CVDSRCNS 01 DSRCNS. VALUE ZERO. X(34) VALUE SPACE. S9(8) VALUE ZERO. CDSRCNS 01 :TAG:. X(8) X(8) VALUE SPACE. 10 :TAG:-SECURLENGTH 10 :TAG:-SECURDATA 05 :TAG:-PARTNER 05 :TAG:-INITIATOR COMP PIC S9(4). S9(8). X(8) X(8) VALUE SPACE. COMP PIC PIC PIC PIC S9(4). VALUE SPACE. CVDSRECV 01 DSRECV.

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 .

Program examples” on page 89. Example: CALL IDCSCONS USING W-IDCSCONS.IDCSCONSX More examples can be found in “Appendix A.7 3. 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.3.1 IDEAL for CICS Parameter passing The IDEAL interface uses the VCOM/CICS Cobol API. Instaed an area is passed that contains the parameters needed. Language 81 .7.

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 .7.2 Copy text The copytexts below is delivered with the VCOM software.3.

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 .

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. view and change the VCOM configuration tables and also view different log files and test various functions. With this function it is possible to monitor conversations and distributions. Other ways may very well exist depending on the setup.1 Operation environment VCOM is equipped with an online TSO/ISPF operator function.4. 4. Environment 85 .0 Environment This section describes the programming and operation environment for VCOM.

object-computer. <=== perform error handling . goback. exec cics start transid ('APL1') resp (w-resp) end-exec if w-resp not = dfhresp(normal) evaluate w-resp when dfhresp(invreq) . ibm-370. Figure 21. This means that a VCOM transaction in a CICS system must finnish before the next VCOM transaction can start. 01 w-resp pic s9(8) comp value zero. not in a parallell mode. In this way VCOM server can initiate many transaction while CICS executes them in a parallell way. To avoid this the transaction initiated by VCOM server should start another transaction (which executes the communication with the server) and then terminate.2 (APPC) session. main-end.4. Proram for enabling parallell CICS transasction 86 VCOMPGM .2 CICS There is a specific VCOM/API to use in a CICS environment. vcom. 4. It does however look the same to the VCOM monitor. .2. id division. This is done over a LU6. program-id. end-evaluate end-if exec cics return end-exec . As a VCOM transaction can be quite lengthy this will be a problem. It does not use the general API that is mentioned in other parts of this manual. procedure division. VCOMPAR. author. VCOM is also able to start CICS transactions. *----------------------------------------------* * MAIN Program main logic * *----------------------------------------------* main section. configuration section. environment division. No application data is sent over this connection. An example of such a program is seen in Figure 21 on page 84. working-storage section. data division.1 Parallell transactions When VCOM server initiates transactions in a CICS system they are received in a sequence mode.

. else error handling endif else error handling end if call CSRLSE . There is no terminal assoiciated with IMS and therefore the IMS transaction should be generated with option NORESP. This is done by sending the transaction code to IMS through an IMS LU6... The application should not try to do insert to the I/O PCB of the same reason. All user data is transferred with standard VCOM calls through standard VCOM API. Environment 87 .3 IMS VCOM is able to start IMS transactions in an IMS MPP. if OK then call CSRECV .. initiation read message from I/O PCB call CSCONR .. Coding of IMS/VCOM transaction. end of program note: no insert to I/O PCB receive question short timeout send answer Figure 22.. An example of a typical service program is shown in Figure 22 on page 85. if OK then action call CSSEND .2 Adapter or by using IMS/APPC..4.. No user data is transferred over this session together with the transaction code.

VCOM will then substitute the question mark character with another character thus making the jobname unique. This can be useful when using REXX programs.4 Batch An application program using VCOM can also be executed as a batch job.6 Started task An application program using VCOM can also be executed as a started task. • • • The name of the dataset that contains the JCL member. The following information is needed by VCOM to be able to submit a batch job. 4. It is also possible to run TSO in batch. 88 VCOMPGM . This problem can however be bypassed using a question mark (?) in the 8th position of the jobname. The expediter table defines if VCOM shall start the receiving program. The name of the member to submit. 4. This batch job can also be started by VCOM when a distribution is received or a conversation is requested. What user id to assign to the job. When there are many submissions at the same time. If this is not specified a default user id will be used.5 TSO A VCOM program may be run in a TSO session.4. the jobs will be queued in the JES system due to duplicate names.

0 Common problems This section is intentionally left blank.5. Common problems 89 .

90 VCOMPGM .

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

CCLIENT AUTHOR.A. 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. SKIP2 DATA DIVISION. * * NEXT THE CLIENT CONNECTS TO THE SERVER AND * * THEN FETCH THE QUESTION FROM THE TERMINAL AND * * SENDS IT TO THE SERVER. VALUE SPACE. '. '. SKIP2 DYNAMIC-SUBPROGRAMS. 77 PROGRAM-NAME SKIP2 PIC X(8) VALUE 'CCLIENT'. * *---------------------------------------------------------* * SAMPLE CONVERSATION PROGRAM * * * * THE PROGRAM ACTS AS A CLIENT IN THAT SENSE * * THAT IT ISSUES QUESTIONS THAT A SERVER THEN * * ANSWERS. 92 VCOMPGM . N. '.1.N SKIP2 *REMARKS. PROGRAM-ID. 01 VALUE VALUE VALUE VALUE VALUE 'CSSEND 'CSRECV 'CSRLSE 'CSCONS 'CSCONR '. 03 QUESTION PIC X(50) 03 ANSWER PIC X(50) 03 PARTNER PIC X(8) SKIP3 EJECT PROCEDURE DIVISION.1 Cobol program Conversation initiator ID DIVISION. * * FIRST THE PARTNER ID IS RETRIEVED FROM THE * * TERMINAL.1 A. VALUE SPACE. WORKING-STORAGE SECTION. 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. VALUE SPACE. '.

CCLIENT OK ' EJECT Appendix A. 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. Program examples 93 . SKIP2 PERFORM BA-CONNECT-SEND PERFORM BB-PROCESS PERFORM BC-DISCONNECT-SEND CONTINUE. SKIP2 PERFORM A-INIT PERFORM B-PROCESS PERFORM Z-FINIT DISPLAY ' GOBACK CONTINUE. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS SECTION. EJECT * *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION.* *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION.

* * IF ERROR DISPLAY ERRORCODE. EJECT * *---------------------------------------------------------* * GET INPUT FROM TERMINAL ABOUT QUESTION AND * * SEND THE QUESTION TO THE SERVER PROGRAM. * *---------------------------------------------------------* * BA-CONNECT-SEND SECTION. EJECT 94 VCOMPGM . * * KEEP ON DOING THIS UNTIL XXX IS RECEIVED. * *---------------------------------------------------------* * BB-PROCESS SECTION. SKIP2 DISPLAY 'QUESTION: ' ACCEPT QUESTION PERFORM UNTIL QUESTION = 'XXX' PERFORM BBA-SEND PERFORM BBA-RECEIVE DISPLAY 'ANSWER.* *---------------------------------------------------------* * GET INPUT FROM TERMINAL ABOUT PARTNER NAME AND * * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. * * IF ERROR. ' ANSWER DISPLAY 'QUESTION: ' ACCEPT QUESTION END-PERFORM CONTINUE. DISPLAY ERROR CODE AND DISCONNECT. 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.

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. * *---------------------------------------------------------* * BBA-RECEIVE SECTION. * *---------------------------------------------------------* * BBA-SEND SECTION. EJECT Appendix A. DISPLAY ERROR CODE AND DISCONNECT. EJECT * *---------------------------------------------------------* * ISSUE A SEND OF THE QUESTION TO THE SERVER. 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. * * IF ERROR. DISPLAY ERROR CODE AND DISCONNECT.* *---------------------------------------------------------* * RETRIVE THE ANSWER FROM VCOM USING THE RECEIVE VERB. * * IF ERROR. Program examples 95 .

96 VCOMPGM . EJECT * *---------------------------------------------------------* * END * *---------------------------------------------------------* * Z-FINIT SECTION. SKIP2 CONTINUE. * *---------------------------------------------------------* * BC-DISCONNECT-SEND SECTION.* *---------------------------------------------------------* * DISCONNECT THE CONVERSATION. 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.

TIMEOUT OR ERROR IS RECEIVED. NEXT THE QUESTION IS * * RECEIVED AND GIVES AN ANSWER. 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. * * * *---------------------------------------------------------* * EJECT ENVIRONMENT DIVISION. * *---------------------------------------------------------* * SAMPLE CONVERSATION PROGRAM * * * * THE PROGRAM ACTS AS A SERVER IN THAT SENSE * * THAT IT RECEIVES QUESTIONS FROM A CLIENT AND * * RETURN AN ANSWER. VALUE SPACE. SKIP2 DYNAMIC-SUBPROGRAMS. Program examples 97 . '. WORKING-STORAGE SECTION.2 Conversation responder ID DIVISION. THE SERVER THEN WAITS* * FOR THE NEXT QUESTION AND KEEP DOING THIS UNTIL * * XXX. CSERVER AUTHOR. 01 VALUE VALUE VALUE VALUE VALUE 'CSSEND 'CSRECV 'CSRLSE 'CSCONS 'CSCONR '.N SKIP2 *REMARKS. '. Appendix A. '. 77 PROGRAM-NAME PIC X(8) VALUE 'CSERVER'. VALUE SPACE. N.A. VALUE SPACE. PROGRAM-ID. * * FIRST THE SERVER SET A CONNECT REQUEST AND WAITS * * FOR A CLIENT TO CONNECT. SKIP2 DATA DIVISION.1. 03 QUESTION PIC X(50) 03 ANSWER PIC X(50) 03 EXPEDITER PIC X(8) SKIP3 EJECT PROCEDURE DIVISION. '.

SKIP2 PERFORM BA-CONNECT-RECEIVE PERFORM BB-PROCESS PERFORM BC-DISCONNECT-RECEIVE CONTINUE. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS SECTION. EJECT CSERVER OK ' 98 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 EXPEDITER TO VCA-EXPEDITER CONTINUE.

* *---------------------------------------------------------* * BA-CONNECT-RECEIVE SECTION. ' QUESTION PERFORM UNTIL QUESTION = 'XXX' DISPLAY 'ANSWER: ' ACCEPT ANSWER PERFORM BBA-SEND PERFORM BBA-RECEIVE DISPLAY 'QUESTION. * * IF ERROR. EJECT Appendix A. DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BB-PROCESS SECTION. Program examples 99 . SKIP2 PERFORM BBA-RECEIVE DISPLAY 'QUESTION. ' QUESTION END-PERFORM CONTINUE. RETRIVE INPUT * * FROM TERMINAL AND RETURN IT TO THE CLIENT * * AS THE ANSWER. * * IF ERROR DISPLAY ERRORCODE. 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.* *---------------------------------------------------------* * GET INPUT FROM TERMINAL ABOUT EXPEDITER NAME AND * * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. EJECT * *---------------------------------------------------------* * GET INPUT FROM VCOM ABOUT QUESTION AND * * DISPLAY IT ON THE TERMINAL. * * KEEP ON DOING THIS UNTIL XXX IS RECEIVED.

* * IF ERROR. 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 . * * IF ERROR. DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-SEND 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. DISPLAY ERROR CODE AND DISCONNECT. * *---------------------------------------------------------* * BBA-RECEIVE SECTION.* *---------------------------------------------------------* * RETRIVE THE ANSWER FROM VCOM BY A RECEIVE.

* *---------------------------------------------------------* * DISCONNECT THE CONVERSATION. SKIP2 CONTINUE. Appendix A. 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. Program examples 101 . * *---------------------------------------------------------* * BC-DISCONNECT-RECEIVE SECTION.

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

SKIP3 EJECT PROCEDURE DIVISION. '. PIC S9(4) PIC S9(4) PIC X PIC X PIC X(8) VALUE 'S'. * *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION. COMP-3 VALUE +80. 77 77 77 77 77 77 77 01 PROGRAM-NAME YES NO SENDFILE-EOF REC-LTH RCODE RCODE-1000 SKIP2 GENERAL-CONSTANTS. 01 VALUE VALUE VALUE VALUE VALUE 'DSSEND 'DSRECV 'DSRLSE 'DSCONS 'DSCONR '. VALUE 'TMATSA '. SKIP2 PERFORM A-INIT PERFORM B-PROCESS-THE-FILE PERFORM Z-FINIT MOVE RCODE TO RETURN-CODE DISPLAY ' DSEND OK ' GOBACK CONTINUE. 03 SENDFILE-REC PIC X(3500). 03 03 03 S T PARTNER PIC X(8) VALUE 'DSEND PIC PIC PIC PIC X X X S9(5) '. COMP SYNC COMP SYNC VALUE +0. EJECT Appendix A. 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. Program examples 103 . VALUE 'N'.WORKING-STORAGE SECTION. VALUE 'Y'. '. '. SKIP2 DYNAMIC-SUBPROGRAMS. VALUE 'T'. VALUE 'N'. VALUE +1000. '.

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. 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.* *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION. EJECT 104 VCOMPGM .

EJECT * *---------------------------------------------------------* * PROCESS A RECORD. * *---------------------------------------------------------* * BA-CONNECT-SEND SECTION. EJECT Appendix A. * *---------------------------------------------------------* * BB-PROCESS-A-RECORD SECTION. * * AT END DISPLAY DISTID AND SENDERTAG. SKIP2 MOVE REC-LTH TO VCA-LENGTH MOVE SENDFILE-AREA TO VCA-DATA PERFORM BBA-SEND CONTINUE.* *---------------------------------------------------------* * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. 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. Program examples 105 . MOVE LENGTH AND DATA AND THEN * * ISSUE THE SEND. * * IF ERROR DISPLAY ERRORCODE.

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. * *---------------------------------------------------------* * BBA-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. 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 106 VCOMPGM . * * IF ERROR DISPLAY THE RETURN CODE AND DISCONNECT.* *---------------------------------------------------------* * SET UP A SEND.

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

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

COMP SYNC COMP SYNC COMP SYNC VALUE +0. PIC X(8) PIC X(80) VALUE 'TMATSA VALUE SPACE. '. VALUE +45. SKIP2 DYNAMIC-SUBPROGRAMS. '. Program examples 109 . SKIP2 PERFORM A-INIT PERFORM B-PROCESS PERFORM Z-FINIT MOVE RCODE TO RETURN-CODE GOBACK CONTINUE. * *---------------------------------------------------------* * MAIN LOGIC * *---------------------------------------------------------* * MAIN SECTION. 01 VALUE VALUE VALUE VALUE VALUE 'DSSEND 'DSRECV 'DSRLSE 'DSCONS 'DSCONR '. EJECT Appendix A. '. 77 77 77 77 01 PROGRAM-NAME RCODE RCODE-45 RCODE-1000 SKIP2 GENERAL-CONSTANTS.WORKING-STORAGE SECTION. 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. 03 03 EXPEDITER RECVAREA PIC X(8) PIC S9(4) PIC S9(4) PIC S9(4) VALUE 'DRECEIVE'. '. VALUE +1000. '.

SKIP2 PERFORM BA-CONNECT-RECEIVE IF VCA-RC = ZERO PERFORM BB-PROCESS PERFORM BC-DISCONNECT-RECEIVE END-IF CONTINUE.* *---------------------------------------------------------* * SETUP * *---------------------------------------------------------* * A-INIT SECTION. EJECT * *---------------------------------------------------------* * MAIN LOOP * *---------------------------------------------------------* * B-PROCESS 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 110 VCOMPGM .

* * AT END DISPLAY DISTID AND SENDERTAG. EJECT * *---------------------------------------------------------* * PROCESS THE DISTRIBUTION. WRITE ALL * * RECORDS TO A FILE. EJECT Appendix A. KEEP ON RECEIVING UNTIL * * THERE ARE NO MORE RECORDS TO RECEIVE. Program examples 111 . 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. * *---------------------------------------------------------* * BB-PROCESS SECTION. * *---------------------------------------------------------* * BA-CONNECT-RECEIVE SECTION.* *---------------------------------------------------------* * SET UP A CONNECT AND IF OK GO ON OTHERWISE * * DISCONNECT. * * IF ERROR DISPLAY ERRORCODE. 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.

* * IF ERROR DISPLAY THE RETURN CODE AND DISCONNECT.* *---------------------------------------------------------* * SET UP A RECEIVE. EJECT 112 VCOMPGM . * *---------------------------------------------------------* * BBA-RECEIVE SECTION. EJECT * *---------------------------------------------------------* * DO THE RELEASE. * *---------------------------------------------------------* * BC-DISCONNECT-RECEIVE SECTION. * * ALWAYS CLOSE DATASET BEFORE RELEASE AND TEST * * RETURN CODE. 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. * * RVALUE CONTROLS THE ACTION * * -1 IS ROLLBACK * * -2 IS HOLD * * IF ERROR DISPLAY THE RETURN CODE. 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 Appendix A. EJECT * *---------------------------------------------------------* * WRITE ROUTINE * *---------------------------------------------------------* * S10-WRITE-RECVFILE SECTION. Program examples 113 . SKIP2 CONTINUE.* *---------------------------------------------------------* * END * *---------------------------------------------------------* * Z-FINIT SECTION. SKIP2 WRITE RECVFILE-REC FROM RECVAREA CONTINUE.

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.2 A.wlen. Send a record and receive * one and then disconnect.2.1 Fortran program Conversation initiator ************************************************************************ * * PROGRAM: CSS * * DESCRIPTION: Connect as a initiator. * ************************************************************************ * * 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* '/.A.arlen * lengths Integer rcplth /0/ * lengths 114 VCOMPGM .

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

wlen.2 Conversation responder ************************************************************************ * * PROGRAM: CSR * * DESCRIPTION: Connect as a responder.A.arlen * lengths Integer rcplth /0/ * lengths 116 VCOMPGM .2. * ************************************************************************ * * 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* '/. receive a record and send * one and then disconnect.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.

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

secur.timeout. & sendertag.arlen * lengths Integer rcplth /0/ * lengths * * PROCEDURE DIVISION: * wlen=LEN(wbuf) secur_lth=0 * Call DSCONS(rc.secur_lth.A.rvalue) * END 118 VCOMPGM .prio) Call DSSEND(rc.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'/.rcpdata.wlen.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.2.convid.rcplth.rcprc.rcppart.wlen.wbuf) Call DSRLSE(rc. & rcpid.partner.convid.convid.

& sendertag.initiator) Call DSRECV(rc.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.arlen * lengths Integer rcplth /0/ * lengths * * PROCEDURE DIVISION: * rlen=LEN(rbuf) secur_lth=0 * Call DSCONR(rc.rlen.convid.A.timeout.convid.convid. & rectyp.2.secur_lth.rlen.expediter. Program examples 119 .rbuf) Call DSRLSE(rc.secur.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/' '/.wlen.rvalue) * END Appendix A.

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

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

This is some test data". i < 2.A. SECINFO secur. &dsid. char data 50“. dsrlse(&rc.h> #include <string. exit(1). if (rc >= VCOM_RC_SUCCESS) { printf("dscons failed. dscons(&rc. &len. ' '.3 Distribution initiator #include <stdio. &dsid. } ". tmo = -1. data). i). long tmo. short rc=0. putchar('Én'). char prio. rc). 8). dssend(&rc. short rvalue. "DS TEST "VTTMAD1 ".h" main(int argc. &rvalue). rc = %dÉn". for (i = 0. RECEIPT recp. } } rvalue = VCOM_RC_SUCCESS. &recp. "Post nr %d. break. len = strlen(data) + 1. &secur. int i. memset(recp. prio = 'N'. } 122 VCOMPGM . if (rc >= VCOM_RC_SUCCESS) { printf("dssend failed.partner.usdlen = 0. secur.3. &tmo. i++) { sprintf(data. &dsid. rc = %dÉn". &prio.h> #include "vcom. "INIT00 "). char *argv “) { DSID dsid. rc). len.

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

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

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 .L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B ./*------------------------------------------------------------*/ /* E N D O F M A I N .

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 apirc = CSRLSE(vcomwork.partner) If apirc = 0 Then Do say "Conversation established.udbrequest) If apirc = 0 Then Do apirc = CSRECV(vcomwork./*--EJECT-----------------------------------------------------*/ /* B _ S E N D */ /*------------------------------------------------------------*/ B_SEND: apirc = CSCONS(vcomwork.tout..csid) End Else Do say "Connect to VCOM failed. rc " apirc End End Else Do say "Send 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 .prefix.csid.prefix.prefix.csid.secur.id " VCOM_convid say "Request:" say udbrequest csid = VCOM_convid apirc = CSSEND(vcomwork..prefix.

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

/*------------------------------------------------------------*/ /* E N D O F M A I N . rc " apirc rcode = 8 End Return 128 VCOMPGM .R O U T I N E S */ /*------------------------------------------------------------*/ /*------------------------------------------------------------*/ /* A _ I N I T */ /* Initiate arg parms etc.L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B . */ /*------------------------------------------------------------*/ 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.

tout) If apirc = 0 Then Do say "Received request:" say VCOM_data apirc = CSSEND(vcomwork..id " VCOM_convid say "Initiator " VCOM_initiator say "Sendertag " VCOM_sendertag csid = VCOM_convid apirc = CSRECV(vcomwork.csid.answer) If apirc = 0 Then Do say "Returned answer:" say answer End Else Do say "Send of answer to VCOM failed.prefix.csid.prefix. rc " apirc End apirc = CSRLSE(vcomwork.prefix./*--EJECT-----------------------------------------------------*/ /* B _ R E C V */ /*------------------------------------------------------------*/ B_RECV: apirc = CSCONR(vcomwork. Program examples 129 .tout.prefix.secur. 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.csid) End Else Do say "Connect to VCOM failed.expediter) If apirc = 0 Then Do say "Conversation established. rc " apirc End End Else Do say "Receive of request from VCOM failed.

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

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./*------------------------------------------------------------*/ /* E N D O F M A I N . Program examples 131 . rc " apirc rcode = 8 End Return Appendix A.

prefix.rvalue) End End Else Do say "Connect to VCOM failed.id " VCOM_distid dsid = VCOM_distid apirc = DSSEND(vcomwork..udbrequest) If apirc = 0 Then Do say "Distribution ended OK" rvalue = "1" apirc = DSRLSE(vcomwork.dsid.. rc " apirc rvalue = "0" apirc = DSRLSE(vcomwork. 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 .partner) If apirc = 0 Then Do say "Distribution established.prefix.secur.prefix.prefix./*--EJECT-----------------------------------------------------*/ /* B _ S E N D */ /*------------------------------------------------------------*/ B_SEND: apirc = DSCONS(vcomwork.dsid.tout.rvalue) End Else Do say "Send to VCOM failed.dsid.

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

/*------------------------------------------------------------*/ /* E N D O F M A I N . rc " apirc rcode = 8 End Return 134 VCOMPGM . */ /*------------------------------------------------------------*/ 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.R O U T I N E S */ /*------------------------------------------------------------*/ /*------------------------------------------------------------*/ /* A _ I N I T */ /* Initiate arg parms etc.L O G I C */ /*------------------------------------------------------------*/ /*--EJECT-----------------------------------------------------*/ /* S U B .

prefix.dsid.prefix.dsid. 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.rvalue) End Else Do say "Receive from VCOM failed.dsid. Program examples 135 .prefix.expediter) If apirc = 0 Then Do say "Distribution established. rc " apirc rvalue = "0" apirc = DSRLSE(vcomwork./*--EJECT-----------------------------------------------------*/ /* B _ R E C V */ /*------------------------------------------------------------*/ B_RECV: apirc = DSCONR(vcomwork.maxlth) If apirc = 0 Then Do say "Data received: " VCOM_data rvalue = "0" apirc = DSRLSE(vcomwork.prefix.secur.rvalue) End End Else Do say "Connect to VCOM failed.tout.id " VCOM_distid dsid = VCOM_distid apirc = DSRECV(vcomwork.

5 A. * * THIS PROGRAM CONNECTS AS A DIALER. * * DIALER IN VD2.5.1 Assembler program Conversation initiator *********************************************************************** * FUNCTION.: TEST OF CONVERSATION SERVICES IN VCOM.. SENDS THE MESSAGE * * VCOM CONVERSATION TEST: FROM PARTNER VT1MAC1 * * RECEIVES THE FOLLOWING ANSWER * * VCOM CONVERSATION TEST: FROM EXPEDITER VT1MAC1 * *********************************************************************** * PRINT NOGEN * 136 VCOMPGM .A..

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

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

*********************************************************************** * * * 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 .

2 Conversation responder *********************************************************************** * FUNCTION. * *********************************************************************** * PRINT NOGEN * 140 VCOMPGM . * * 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.5. THE RECEIVED MESSAGE IS ALSO WRITTEN * * TO THE SYSOUT FILE..A.: TEST OF CONVERSATION SERVICES IN VCOM.

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

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

Program examples 143 .RECFM=FB LTORG END Appendix A.DSORG=PS.*********************************************************************** * * * 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.LRECL=132.MACRF=PM.

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

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

*********************************************************************** * * * 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 .

Program examples 147 . * * THIS PROGRAM CONNECTS AS AN RESPONDER.. * * AFTER RECEIVING A DISTRIBUTION IT TESTS * * IF THERE ARE MORE DISTRIBUTIONS WITHIN VCOM * *********************************************************************** * PRINT NOGEN * Appendix A.5.: TEST OF DISTRIBUTION SERVICES IN VCOM..A. RECEIVES A * * DISTRIBUTION AND DELETES THE DISTRIBUTION.4 Distribution responder *********************************************************************** * FUNCTION.

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

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

*********************************************************************** * * * 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.MACRF=PM.RECFM=FB LTORG END 150 VCOMPGM .DSORG=PS.LRECL=132.

CONFIGURATION SECTION. COPY DSCONR REPLACING ==:TAG:== BY ==DSCONR==. Appendix A. MATS ANDERSSON DATE-WRITTEN. WORKING-STORAGE SECTION. * * * *---------------------------------------------------------* * ENVIRONMENT DIVISION. CICSCOB AUTHOR. OBJECT-COMPUTER IBM-370.6 CICS Cobol program ID DIVISION. MARS 1993 SKIP2 *REMARKS. PROGRAM-ID. O1 FILLER PIC X(14) VALUE '***VC14 PWS***'. DATA DIVISION.A. COPY DSRLSE REPLACING ==:TAG:== BY ==DSRLSE==. COPY DSRECV REPLACING ==:TAG:== BY ==DSRECV==. Program examples 151 . * *---------------------------------------------------------* * SAMPLE DISTRIBUTION PROGRAM * * * * THE PROGRAM RECEIVES A DISTRIBUTION.

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

74 Dynamic subprograms 35 Parameter passing 34. 120. 31 Application protocol . 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.Question/Answer protocol 1 31 Application protocol . 73 Cobol program 92 Conversation initiator 92 Conversation responder 97 Distribution initiator 102 Distribution responder 108 Coding IMS transactions 87 Common problems 89 . 127. 133. 136 Conversation responder 97. 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. 121. 116. 114.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. 119. 140 Conversation services 23 Application protocol 31 Data header 28 Error handling 29 Fetch connect parameters 27 printable data 30 Copy text 35. 122. 124.Index A API parameter description 43 API verb description 48 Application protocol 24. 123. 144 Distribution responder 108. 130. 118. 73 Copy text 35.

72 printable data 22. 42 Interface code 37. 38. 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. 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 . 81 Parameter passing 37. 42 R Receipt 59. 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.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. 86 Parameter description 43 Parameter passing 34. 37. 73. 72. 38.

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 .