Programmers Manual

Download Programmers Manual

Post on 30-Oct-2015

49 views

Category:

Documents

0 download

Embed Size (px)

DESCRIPTION

Mainframe

TRANSCRIPT

<ul><li><p>VCOM for OS/390 ProgrammersManual</p><p>Version 3.2.1</p><p>Document Number: VM-5105-321</p><p> Copyright 2000 NetSys Software Group AB</p></li><li><p>VM-5105-321 First Edition (March 2000)This edition applies to Version 3 Release 2 Modification Level 1 of VCOMfor OS/390.</p><p>NetSys Software Group ABS-431 85 Mlndal</p><p> SwedenTel +46 31-720 60 00Fax +46 31-27 50 10</p></li><li><p> PrefaceThis manual describes methods used with VCOM and specific languageand environment dependencies.</p><p>Organization of this manualChapter 1: contains an introduction to the VCOM system.</p><p>Chapter 2: contains a description of various methods used.</p><p>Chapter 3: contains a description of languages supported for a specificenvironment and how the VCOM verbs are coded in that language.</p><p>Chapter 4: contains a description of the programming environment.</p><p>Chapter 5: contains a summary of common problems and troubleshooting.</p><p>Appendix A: contains a number of programming examples.</p><p>Related publicationsVCOM API Manual: describes the VCOM Application ProgrammingInterface.</p><p>VM-5102 VCOM for OS/390 Reference Manual describes how a VCOMfor OS/390 system is installed and customized for installation needs.</p><p>VM-5104 VCOM for OS/390 Operator Manual: describes the VCOM forOS/390 operator function and the commands used for the VCOM forOS/390 system.</p><p>VM-5103 VCOM for OS/390 Message Manual: contains messages andinformation codes generated by the VCOM for OS/390 system.</p><p> Preface 3</p></li><li><p> 4 VCOMPGM</p></li><li><p> Contents1.0 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9</p><p>2.0 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1 Distribution services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11</p><p>2.1.1 Fetch connect parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.2 Data header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12</p><p>2.1.2.1 Distribution with many records . . . . . . . . . . . . . . . . . . . . . . . 132.1.2.2 Distribution with few records . . . . . . . . . . . . . . . . . . . . . . . . 14</p><p>2.1.3 Sequence of VCOM and DB calls . . . . . . . . . . . . . . . . . . . . . . . 142.1.3.1 Calling sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.1.3.2 Two-phase commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16</p><p>2.1.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.1.5 Printable data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.1.6 Receipt handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21</p><p>2.2 Conversation services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22</p><p>2.2.1.1 Application protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2.1.2 Half-Duplex Flip-Flop protocol . . . . . . . . . . . . . . . . . . . . . . . 222.2.1.3 Speaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2.1.4 Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.2.1.5 Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.2.1.6 Transaction types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.2.1.7 Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.2.1.8 More data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24</p><p>2.2.2 Fetch connect parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.2.3 Data header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.2.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.2.5 Printable data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.2.6 Application protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29</p><p>2.2.6.1 Application protocol - Question/Answer protocol 1 . . . . . . . . 292.2.6.2 Application protocol - Question/Answer protocol 2 . . . . . . . . 30</p><p>3.0 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.1 Cobol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32</p><p>3.1.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.1.2 Copy text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.1.3 Dynamic subprograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33</p><p>3.2 Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.2.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.2.2 Interface code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35</p><p>3.3 C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3.2 Include files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3.3 Interface code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40</p><p>3.4 REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.4.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.4.2 Parameter description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.4.3 API verb description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463.4.4 Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46</p><p> Contents 5</p></li><li><p> 3.4.5 Initialisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473.4.5.1 VCOMINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473.4.5.2 VCOMFIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47</p><p>3.4.6 CSCONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.4.7 CSCONR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503.4.8 CSSEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523.4.9 CSRECV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533.4.10 CSRLSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553.4.11 DSCONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563.4.12 DSCONR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.4.13 DSSEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.4.14 DSRECV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633.4.15 DSRLSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653.4.16 DSRCNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673.4.17 DSPRLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69</p><p>3.5 Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.5.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70</p><p>3.6 Cobol for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.6.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.6.2 Copy text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72</p><p>3.7 IDEAL for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.7.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.7.2 Copy text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80</p><p>4.0 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834.1 Operation environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834.2 CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84</p><p>4.2.1 Parallell transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844.3 IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854.4 Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864.5 TSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864.6 Started task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86</p><p>5.0 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87</p><p>Appendix A. Program examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89A.1 Cobol program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90</p><p>A.1.1 Conversation initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90A.1.2 Conversation responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95A.1.3 Distribution initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100A.1.4 Distribution responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106</p><p>A.2 Fortran program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112A.2.1 Conversation initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112A.2.2 Conversation responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114A.2.3 Distribution initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116A.2.4 Distribution responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117</p><p>A.3 C program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118A.3.1 Conversation initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118A.3.2 Conversation responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119A.3.3 Distribution initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120A.3.4 Distribution responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121</p><p>A.4 REXX program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122A.4.1 Conversation initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122A.4.2 Conversation responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125A.4.3 Distribution initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128A.4.4 Distribution responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131</p><p>A.5 Assembler program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134A.5.1 Conversation initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134A.5.2 Conversation responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138A.5.3 Distribution initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142A.5.4 Distribution responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145</p><p>6 VCOMPGM</p></li><li><p> A.6 CICS Cobol program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149A.7 CICS IDEAL program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151</p><p>Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153</p><p> Contents 7</p></li><li><p> 8 VCOMPGM</p></li><li><p> List of IllustrationsFigure 1. Distribution methods, fetch connect parameters . . . . . . 11Figure 2. Distribution methods, data header . . . . . . . . . . . . . . . . 12Figure 3. Distribution with many records . . . . . . . . . . . . . . . . . . 13Figure 4. Distribution with few records . . . . . . . . . . . . . . . . . . . . 14Figure 5. Distribution methods, sequence of VCOM and DB calls 14Figure 6. Call sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Figure 7. Program logic for initiating program . . . . . . . . . . . . . . . 17Figure 8. Reconnect logic for initiator . . . . . . . . . . . . . . . . . . . . 17Figure 9. Program logic for responder . . . . . . . . . . . . . . . . . . . . 18Figure 10. Distribution methods, error handling . . . . . . . . . . . . . . 19Figure 11. Distribution methods, printable data . . . . . . . . . . . . . . 20Figure 12. Distribution methods, receipt handling . . . . . . . . . . . . . 21Figure 13. Conversation methods, fetch connect parameters . . . . 25Figure 14. Conversation methods, data header . . . . . . . . . . . . . . 26Figure 15. Conversation data layout . . . . . . . . . . . . . . . . . . . . . . 26Figure 16. Conversation methods, error handling . . . . . . . . . . . . . 27Figure 17. Conversation methods, printable data . . . . . . . . . . . . . 28Figure 18. Conversation methods, application protocol . . . . . . . . . 29Figure 19. Application protocol, One question . . . . . . . . . . . . . . . 29Figure 20. Application protocol, Several questions . . . . . . . . . . . . 30Figure 21. Proram for enabling parallell CICS transasction . . . . . . 84Figure 22. Coding of IMS/VCOM transaction. . . . . . . . . . . . . . . . 85</p><p> List of Illustrations 9</p></li><li><p> 1.0 IntroductionVCOM is designed to provide a common interface to data communi-cations for application system development. This programming interfaceis consistent across various computer environments, i.e. IBMmainframes, IBM midrange (AS/400), IBM PC's, DEC machines, UNIXetc.</p><p>The main purpose of VCOM is to provide services for program-to- pro-gram communication for distributed application systems. A distributedapplication system in this context is a system consisting of at least twoprograms, co-operating in order to perform a function. Normally, the co-operating programs would be geographically separated, i.e. they wouldrun in different computers or environments. They may, however, also runin the same computer, using VCOM as the tool for data transfer.</p><p>VCOM provides service to an application program in two areas:</p><p> communications services</p><p> addressing services</p><p>This manual is intended to help the programmer or system developer todesign and write applications using VCOM. The manual is also intendedto form a complement to the VCOM API manual.</p><p> Introduction 11</p></li><li><p> 12 VCOMPGM</p></li><li><p> 2.0 MethodsThis section contains a description of methods used with VCOM.</p><p>Methods for both VCOM conversations and distributions are discussed.Even though some recommendations are given in...</p></li></ul>