+ All Categories
Home > Documents > Programmers Manual

Programmers Manual

Date post: 30-Oct-2015
Category:
Upload: ashwin-reddy
View: 101 times
Download: 1 times
Share this document with a friend
Description:
Mainframe
Popular Tags:

of 157

Transcript
  • VCOM for OS/390 ProgrammersManual

    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 VCOMfor OS/390.

    NetSys Software Group ABS-431 85 Mlndal

    SwedenTel +46 31-720 60 00Fax +46 31-27 50 10

  • PrefaceThis manual describes methods used with VCOM and specific languageand environment dependencies.

    Organization of this manualChapter 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 specificenvironment 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 troubleshooting.

    Appendix A: contains a number of programming examples.

    Related publicationsVCOM API Manual: describes the VCOM Application ProgrammingInterface.

    VM-5102 VCOM for OS/390 Reference Manual describes how a VCOMfor OS/390 system is installed and customized for installation needs.

    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.

    VM-5103 VCOM for OS/390 Message Manual: contains messages andinformation codes generated by the VCOM for OS/390 system.

    Preface 3

  • 4 VCOMPGM

  • Contents1.0 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

    2.0 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1 Distribution services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    2.1.1 Fetch connect parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.2 Data header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

    2.1.2.1 Distribution with many records . . . . . . . . . . . . . . . . . . . . . . . 132.1.2.2 Distribution with few records . . . . . . . . . . . . . . . . . . . . . . . . 14

    2.1.3 Sequence of VCOM and DB calls . . . . . . . . . . . . . . . . . . . . . . . 142.1.3.1 Calling sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.1.3.2 Two-phase commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    2.1.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.1.5 Printable data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.1.6 Receipt handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

    2.2 Conversation services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

    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

    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

    2.2.6.1 Application protocol - Question/Answer protocol 1 . . . . . . . . 292.2.6.2 Application protocol - Question/Answer protocol 2 . . . . . . . . 30

    3.0 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.1 Cobol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

    3.1.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.1.2 Copy text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.1.3 Dynamic subprograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

    3.2 Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.2.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.2.2 Interface code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

    3.3 C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3.2 Include files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3.3 Interface code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

    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

    Contents 5

  • 3.4.5 Initialisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473.4.5.1 VCOMINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473.4.5.2 VCOMFIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

    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

    3.5 Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.5.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

    3.6 Cobol for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.6.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.6.2 Copy text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

    3.7 IDEAL for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.7.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.7.2 Copy text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

    4.0 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834.1 Operation environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834.2 CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

    4.2.1 Parallell transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844.3 IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854.4 Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864.5 TSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864.6 Started task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

    5.0 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

    Appendix A. Program examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89A.1 Cobol program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

    A.1.1 Conversation initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90A.1.2 Conversation responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95A.1.3 Distribution initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100A.1.4 Distribution responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

    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

    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

    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

    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

    6 VCOMPGM

  • A.6 CICS Cobol program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149A.7 CICS IDEAL program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

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

    Contents 7

  • 8 VCOMPGM

  • 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

    List of Illustrations 9

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

    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.

    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 todesign and write applications using VCOM. The manual is also intendedto form a complement to the VCOM API manual.

    Introduction 11

  • 12 VCOMPGM

  • 2.0 MethodsThis section contains a description of methods used with VCOM.

    Methods for both VCOM conversations and distributions are discussed.Even though some recommendations are given in this chapter, there mayvery well be occasions where other methods are wanted, needed orbetter suited. VCOM will work well in many other ways than the onesdescribed in this section.

    Many of the subjects described are common for both conversation anddistribution services but are discussed separately.

    2.1 Distribution servicesThe following paragraph will discuss various matters concerning theVCOM distribution services (VCOM/DS). VCOM distributions are used tosend messages between two applications in an asynchronous way, formore information see the VCOM API manual.

    The subjects covered are: Connect parameters

    Data headers

    Sequence of VCOM and DB calls

    Error handling

    Character sets and printable data

    Receipt handling

    2.1.1 Fetch connect parameters

    +--------------------------+

    ! !! fetch connect parameters !

    ! ! +--------------------------+

    Figure 1. Distribution methods, fetch connect parameters

    Methods 13

  • It is recommended that the connect parameters are stored in 'applicationdatabase', parameter library or another suitable place and can be readat connect time. The reason for this is to

    allow increased flexibility.

    increase the tuning possibilities (e.g: time-out values).Values that are suited to be read at connect time are:

    Partner

    Expediter

    Initiator

    Time out

    Priority

    Receipt information

    Security information

    Sendertag

    Maximum receive length

    If these values are stored in a database used by many VCOM applica-tions, a key into that table must be defined to be able to identify the pa-rameters to use. The key can for instance be program name or subjectetc.

    2.1.2 Data header

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! ! +--------------------------+

    Figure 2. Distribution methods, data header

    The data sent between the two programs must be understood by bothends . This fact indicates that the layout and structure of the data is im-portant. The data can be formatted in many different ways depending onapplication needs. One criteria to decide how this should be done is thenumber of records sent. Another criteria is the kind of information neededto be transmitted together with the data, like application names, messagetype etc.

    14 VCOMPGM

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

    2.1.2.1 Distribution with many records

    First record ------------

    Subject From appl To appl From program

    +------------------------------------------------+

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

    Record type

    +---------------------------------------------+

    ! ! ! ! !! ORDER header ! 120034 ! 078820 ! 1994-12-01 !! ! ! ! !

    +---------------------------------------------+

    +------------------------------------------------------+

    ! ! ! ! ! !! ORDER row ! 001 ! 121678 ! 1200 ! VCOM for MVS !

    ! ! ! ! ! ! +------------------------------------------------------+

    +------------------------------------------------------+

    ! ! ! ! ! !! ORDER row ! 002 ! 150622 ! 5000 ! Network monitor !

    ! ! ! ! ! ! +------------------------------------------------------+

    .

    .

    .

    .

    .

    Figure 3. Distribution with many records

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

    Methods 15

  • 2.1.2.2 Distribution with few records

    Subject From To From Recordappl appl program type

    +----------------------------------------------------------------+

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

    +----------------------------------------------------------------+

    .

    .

    .

    Figure 4. Distribution with few records

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

    2.1.3 Sequence of VCOM and DB calls

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! !

    ! sequence VCOM / DB calls ! ! ! +--------------------------+

    Figure 5. Distribution methods, sequence of VCOM and DB calls

    When the distribution data is used together with database update trans-actions some important circumstances and conditions should be consid-ered.

    Actions to take:

    The amount of data in one distribution ought to be the same as forthe database transaction. This makes it possible to rollback thedistribution and transaction.

    16 VCOMPGM

  • Commit towards the database should be done before DSRLSE to-wards VCOM. In case of an error it is possible to make a Roll-Back(delete) of the distribution.

    If the distribution (application data) is only written to a file, this fileshould be closed before the DSRLSE verb is issued.

    Conditions to consider:

    When sending a distribution, all information about the distribution isdeleted if the application is ended abnormally before DSRLSE orDSPRLSE.

    When receiving a distribution, the distribution is put back on thedistribution queue (retaining its position) if the application is endedabnormally before DSRLSE.

    2.1.3.1 Calling sequence

    Update database actions and VCOM actions should be synchronizedwith each other. A transaction start corresponds to theDSCONS/DSCONR verbs in VCOM. Database actions like Update, In-sert and Delete correspond to the DSSEND and DSRECV verbs andfinally the Commit/Rollback correspond to DSRLSE (normal or rollback).

    Database VCOM

    +----------------------+ +----------------------+

    ! Start transaction ! ! DSCONS / DSCONR ! +----------------------+ +----------------------+

    +----------------------+ +----------------------+

    ! Update/Insert/Delete ! ! DSSEND / DSRECV ! +----------------------+ +----------------------+

    .

    .

    .

    +----------------------+

    ! Commit ! +----------------------+

    +----------------------+

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

    +----------------------+

    ! Rollback ! +----------------------+

    +----------------------+

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

    Figure 6. Call sequence

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

    Methods 17

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

    2.1.3.2 Two-phase commit

    In the VCOM architecture it is specified how 'two-phase commit' can beobtained when using VCOM distribution services. To be able to do this,VCOM offers two extra verbs, DSPRLS and DSRCNS. These verbs areoptional and should only be used by applications that need 'two-phasecommit'.

    DSPRLS (Distribution Services Prepare to Release) is used to tell VCOMto save the data on disc. This also makes it possible to restart the dis-tribution from that point and that is done with DSRCNS (DistributionServices Re-Connect). Both these verbs may only be used on the initi-ating side.

    It is only possible to make ONE DSPRLS for each distribution. The nextaction after a DSPRLS must be an ordinary release DSRLSE or an ab-normal end of the program. This indicates as mentioned before that thedata in one distribution should correspond to one database transaction(one commit).The distribution id should always be saved in the application database.The status of the distribution is then known in case of a failure.

    If the transaction is abnormally ended, the distribution may be re-connected using the DSRCNS verb specifying the distribution id to whichit wants to re-connect or a search criteria for distributions that have notbeen correctly concluded.

    If the commit is successful, the distribution is ended with DSRLSE normaland if the commit fails the distribution ends with DSRLSE rollback.

    At the responding side the same type of function may be performedwithout special verbs. If the transaction ends abnormally the distributionis always put back on the distribution queue (rollback). If the commitfails, the application may end the distribution with DSRLSE rollback toput it back on the queue, or DSRLSE hold to put it into hold for furtherinvestigations. And finally, if the commit is successful, the applicationends the distribution with DSRLSE normal.

    Figure Figure 7 on page 17 shows the program logic for an initiatingprogram (the application that sends the distribution).

    18 VCOMPGM

  • Start transactionCall DSCONS (rc,...)Retrieve data to send from the databaseWhile (data to send)

    Call DSSEND (rc,...) Update database

    Retrieve more data to send Enddo

    Call DSPRLS (rc,...)Save distribution id

    COMMITIf (Commit = OK)

    Call DSRLSE (normal) Else

    Call DSRLSE (rollback) Endif

    Figure 7. Program logic for initiating program

    The following is worth mentioning:

    The distribution id should be saved in the application database di-rectly after the DSPRLS verb but before the commit. In this way, thedistribution id is saved together with the other database updates andthe id can then be compared with id's retrieved when using theDSRCNS verb.

    DSPRLS is made before the commit and with the DSPRLS verbVCOM will save the distribution and wait for the DSRLSE verb. De-pending on the outcome of the commit the DSRLSE can be eithernormal or rollback.

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

    Call DSRCNS (rc,search criteria,...)While (RC = success)

    Check if distribution id is in application databaseIf (distribution id found)

    Call DSRLSE (normal) Else

    Call DSRLSE (rollback) Endif

    Call DSRCNS (rc,search criteria,...) Enddo

    Figure 8. Reconnect logic for initiator

    DSRCNS is used to re-connect to any distribution that is in status'Prepared to release' and that matches the search criteria specified.The verb can be used by the initiating program itself or it is possibleto develop a general supervising program.

    Whether to include the re-connect logic in the initiating program orto implement a supervising program depends upon a number offactors. The following need to be considered:

    Methods 19

  • Performance of the initiating program.

    Sequence control.

    Supervising strategy.

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

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

    Call DSCONR (rc,...)While (RC = success)

    Start transactionCheck if the distribution id exists in application databaseIf (distribution id found)

    Call DSRLSE (normal) Else

    Call DSRECV (rc,...)While (RC = success)

    Update databaseCall DSRECV (rc,...)

    EnddoSave distribution id in application database

    COMMITIf (Commit = OK)

    Call DSRLSE (normal) Else

    Call DSRLSE (rollback) Endif Endif

    Call DSCONR (rc,...) Enddo

    Figure 9. Program logic for responder

    When the program starts to receive a distribution (DSCONR), the dis-tribution id is used to look in the application database to see if it alreadyhas been processed or not.

    If the distribution id is found, it is an indication that the following hasoccurred.

    The program was interrupted the last time this distribution wasprocessed. The fact that the distribution id exists indicates that theupdates in the database have been made. The distribution is in thiscase already processed and the only thing left is to perform aDSRLSE normal.

    If the distribution id is not found in the application database, one ofthe two following events may have occurred.

    The program was interrupted the last time this distribution wasprocessed. The fact that the distribution id is not found indicatesthat the database was not updated and that the distributionshould be processed again.

    20 VCOMPGM

  • The distribution has not been processed before (this is thenormal case).

    2.1.4 Error handling

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! !

    ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! ! +--------------------------+

    Figure 10. Distribution methods, error handling

    Proper error handling is always important, also when using VCOM. Mat-ters that need to be considered are:

    What return codes the program should handle.

    What return codes/events should result in the program performingan EXIT (ends).

    VCOM uses return codes with 4 bytes. When using these return codesin the program it is better to use symbolic names instead, supplied incobol copytexts or C include files etc.

    It is suggested that these return codes are grouped together. Thecatagorization below is an example.

    Category DescriptionNormal Normal return codes that the application should handle

    (for instance 'No more records').Try again Return codes that indicate that the the program should

    try again (for instance different types of time-out's).Try later Return codes indicating that VCOM is not available and

    an attempt should be done later (for instance 'VCOM notavailable')

    Exit Non recoverable errors requiring intervention by VCOMoperator or application owner.

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

    Methods 21

  • (distribution id, partner, expediter etc) should be logged for problem de-termination purposes. Following symbolic return codes should at leastbe handled by the application:

    Return code DescriptionSuccess Ok (Normal)EOF No more records (Normal)Timeout Timeout for DSCONS or DSCONR (Try again)Not available VCOM not available (Try later)Security error Security data error (Exit)

    2.1.5 Printable data

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! !

    ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! ! +--------------------------+

    Figure 11. Distribution methods, printable data

    VCOM can do character translation on request. VCOM can only translatecharacters that are represented in ISO 8859-1 (ISO-latin-1) and thecharacter sets used by the applications. A translation error occurs whena character does not exist in both user character sets and in ISO 8859-1.For this reason the recommendation is only to use 'printable data' whentransferring text that should be understood by both programs.

    VCOM also has the ability to transfer data as binary. No translation isthen performed by VCOM.

    Note: It is not possible to mix binary and translation mode within onedistribution.

    2.1.6 Receipt handling

    22 VCOMPGM

  • +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! !

    ! sequence VCOM / DB calls ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! +--------------------------+ +-! ! ! receipt handling ! ! ! +--------------------------+

    Figure 12. Distribution methods, receipt handling

    When using VCOM distribution services, the data is always transferredto the other application if no timeout value for the distribution has beenspecified. This is usually insufficient for as verification that the data hasbeen delivered and that the result was correct. In some cases (when itis necessary), the application developers need to decide how the resultof the distribution ought to be verified. In VCOM, this can be accom-plished in several ways:

    Use VCOM receipt handling.

    Send a ordinary distribution as verification.

    Use sequence number in the distributions so that later distributionscan verify previous distributions.

    . . .

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

    2.2 Conversation servicesThis section will discuss various matters concerning the VCOM conver-sation services (VCOM/CS). VCOM conversations are used to sendmessages between two applications in a synchronous way, for more in-formation see the VCOM API manual.

    The subjects covered are: Definitions

    Connect parameters

    Methods 23

  • Data headers

    Error handling

    Character sets and printable data

    Application protocol

    2.2.1 DefinitionsWhen using VCOM/CS, the terminology may need to be expanded. Oneof the advantages with VCOM is that it uses a common terminologyacross the different computer platforms. The definitions made here arenot included in the VCOM specification but, a terminology like this isneeded.

    2.2.1.1 Application protocol

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

    2.2.1.2 Half-Duplex Flip-Flop protocol

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

    2.2.1.3 Speaker

    The program with has the authority to speak (CSSEND) is the currentspeaker.

    The speaker/listener role can be alternated during the connection ac-cording to the application protocol.

    The programs cannot have the same role at the same time.

    The initiator program is normally the first speaker but does not have tobe. This is defined in the application protocol.

    2.2.1.4 Listener

    The program without the authority to speak (CSSEND) is the current lis-tener (CSRECV).The speaker/listener role can be alternated during the connection ac-cording to the application protocol.

    The programs cannot have the same role at the same time.

    2.2.1.5 Transaction

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

    24 VCOMPGM

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

    2.2.1.6 Transaction types

    Within an application area, the following transaction types can be seenas examples depending on the kind of service requested (or demanded).Lock: A request from the current speaker to lock a database entry forlater update. A Lock transaction should always be responded to by aConfirm or Reject transaction. A typical example would be to lock anOrder entry in a remote data base with the intention to make an update(or Unlock) at a later stage.Unlock: A request from the current speaker to unlock a previous lockeddata base entry. An Unlock transaction should always be responded tobya Confirm transaction.

    Request: A Request from the current speaker for remote data baseupdate at the listener site. A Request should always be replied by aConfirm or Reject transaction. An Order Change Request is a typicalexample.

    Demand: A Demand from the current speaker for remote database up-date at the listener site. The Demand transaction should be respondedtoby a Confirm transaction. No negotiation is possible. The transactionis normally preceded by a confirmed lock. An Order Change Demand(forced update) is a typical example.Query: In this case the current speaker is requesting remote data baseretrieve only. The Query transaction should be responded to by a Con-firm or Reject transaction depending on the result.Confirm: Normal response to a Lock, Unlock, Request, Demand orQuery transaction.

    Reject Abnormal response to a Lock, Request, Demand or Query trans-action.

    Error: An error transaction is a request from the current speaker for animmediate shut down and can occur at any time within another trans-action (More Data = NO, see More data on page 24) or as an owntransaction.

    The main reason for introducing the error transaction is to give a possi-bility to inform the other side that the protocol has been violated. Thespeaker should perform error handling procedures, abort the transaction

    Methods 25

  • in progress and disconnect when an error transaction is transmitted. Thelistener should perform error handling procedures, abort the transactionin progress and disconnect.

    The Error transaction should be used when possible (instead of merelydisconnecting the conversation) in order for both parts to be able tocontrol disconnection. A disconnect (CSRLSE) will cause an unexpectedend of data or time out to occur if not preceded by an Error transaction.The Error transaction should not be used for unexpected VCOM returncodes.

    The error transaction should contain a reason code and an error code.Reason code examples:

    Protocol violation

    Internal system error

    Protocol violation error codes examples:

    Invalid record length

    Maximum number of records exceeded

    Invalid record type

    Invalid record data

    2.2.1.7 Record

    A 'protocol unit' included in a transaction. Records normally have somekind of structure and sort order within a transaction. The maximumnumber of records within a transaction needs to be specified in order toprevent application program buffer overflow from occuring.

    2.2.1.8 More data

    A means to control the record flow from speaker to listener and indicatethe end of the transaction to the listener. The field should be includedas a standard item in each record. More data equals YES indicate thatthere are more records to be received. More data equals NO means thatthis was the last record in the transaction.

    When last record is sent/received the speaker/listener role is alternated.

    26 VCOMPGM

  • 2.2.2 Fetch connect parameters

    +--------------------------+

    ! !! fetch connect parameters !

    ! ! +--------------------------+

    Figure 13. Conversation methods, fetch connect parameters

    It is recommended that the connect parameters are stored in an 'appli-cation database', parameter library or another suitable place and can beread at connect time. The reason for this is to

    increase flexibility.

    increase the tuning possibilities (ex: time-out values).Values that are suited to be read at connect time are:

    Partner

    Expediter

    Initiator

    Time out

    Security information

    Sendertag

    Maximum receive length

    If these values are stored in a database that are used by many VCOMapplications, a key into that table must be defined to be able to identifythe parameters to use. The key can for instance be program name orsubject etc.

    Methods 27

  • 2.2.3 Data header

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! ! +--------------------------+

    Figure 14. Conversation methods, data header

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

    Transaction type !

    ! More data indicator ! !

    ! ! Subject From To From Record! ! appl appl program type

    ! ! +-------------------------------------------------------------------+

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

    Figure 15. Conversation data layout

    28 VCOMPGM

  • 2.2.4 Error handling

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! ! +--------------------------+

    Figure 16. Conversation methods, error handling

    Proper error handling is always important and is so also when usingVCOM. Matters that need to be considered are:

    What return codes the program should handle.

    What return codes/events should result in the program performingan EXIT (ends).

    VCOM uses return codes with 4 bytes. When using these return codesin the program it is better to use symbolic names, supplied in cobolcopytexts or C include files.

    It is suggested that these return codes are grouped together. Thecatagorisation below is an example.

    Category DescriptionNormal Normal return codes that the application should handle

    (for instance CSRLSE).Try again Return codes that indicate that the the program should

    try again (for instance different types of time-out's).Try later Return codes indicating that VCOM is not available and

    an attempt should be done later (for instance 'VCOM notavailable')

    Exit Non recoverable errors requiring intervention by VCOMoperator or application owner.

    This section does not describe the symbolic names for the return codes.Refer to the 'Language chapter' in this manual. Most of the return codesare not very likely to be issued. The most common action after a returncode test is of the type 'EXIT'. When these types of return codes occur,the application should exit the VCOM conversation in a way that isagreed for this specific case. The return code and the VCOM identityparameters (distribution id, partner, expediter etc) should be logged forproblem determination purposes. Following symbolic return codesshould at least be handled by the application:

    Return code DescriptionSuccess Ok (Normal)CSRLSE CSRLSE received (Normal)

    Methods 29

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

    2.2.5 Printable data

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! ! +--------------------------+

    Figure 17. Conversation methods, printable data

    VCOM can do character translation upon request. VCOM can onlytranslate characters that are represented in ISO 8859-1 (ISO-latin-1) andthe charactersets used by the applications. If a character does not existin both user charactersets or in ISO 8859-1, a translation error will occur.For this reason the recommendation is only to use 'printable data' whentransferring text that should be understood by both programs.

    VCOM also has the possibility to transfer data as binary, in which caseVCOM does not perform any translation.

    Note: It is not possible to mix binary and translation mode within oneconversation.

    30 VCOMPGM

  • 2.2.6 Application protocol

    +--------------------------+

    ! !! fetch connect parameters !

    ! +--------------------------+ +-! ! ! data header ! ! +--------------------------+ +-! ! ! error handling ! ! +--------------------------+ +-! ! ! printable data ! ! +--------------------------+ +-! ! ! application protocol ! ! ! +--------------------------+

    Figure 18. Conversation methods, application protocol

    The application protocol set up between a pair of application programscontrol the dataflow, specifies the data layout that is sent and what to doin error situations. This section, however, will only describe the data flow.Transaction types and error handling is described earlier in this chapter.

    The protocols described here are of the type 'question/answer'.

    2.2.6.1 Application protocol - Question/Answer protocol 1This type of protocol is used when there is always only one questionwithin each conversation. The question can result in several answers. InFigure 19 on page 29, the logic may be seen from the initiating program'spoint of view. This protocol is for example suitable when the respondingprogram is an IMS or CICS transaction.

    Connect (CSCONS)

    Send Question (CSSEND)

    loop until no more data to receive

    Receive Answer (CSRECV)

    end loop

    Disconnect (CSRLSE)

    Figure 19. Application protocol, One question

    Methods 31

  • 2.2.6.2 Application protocol - Question/Answer protocol 2This type of protocol is used when the conversation can include severalquestions. Each question can result in several answers. In Figure 20 onpage 30, the logic may be seen from the initiating program's point of view.This protocol is for example suitable when the responding program is amonitor that can handle infinite conversations or if a another process isstarted for each conversation.

    Connect (CSCONS)

    Send Question (CSSEND)

    loop until no more questions

    loop until no more data to receive

    Receive Answer (CSRECV)

    end loop

    Send Question (CSSEND)

    end loop

    Send End mark (CSSEND)

    Disconnect (CSRLSE)

    Figure 20. Application protocol, Several questions

    32 VCOMPGM

  • 3.0 LanguageThis section describes of how the VCOM verbs are coded for a specificlanguage. 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 sameway as Cobol does.

    Language 33

  • 3.1 Cobol

    3.1.1 Parameter passingAll calls to VCOM are of the type 'called by reference'. Example:

    CALL CSCONS USING VCA-RC VCA-CONVID VCA-SECUR VCA-TIMEOUT VCA-SENDERTAG VCA-PARTNER VCA-INITIATOR END-CALL

    More examples can be found in Appendix A. Program examples onpage 89.

    34 VCOMPGM

  • 3.1.2 Copy textThe 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 subprogramsIt is possible to choose whether the VCOM API should be loaded dy-namically or if it should be linked together with the application. A dy-namic load of the API is recommended. The following definitions need tobe made in the program:

    Language 35

  • 01 DYNAMIC-SUBPROGRAMS. 03 CSSEND PIC X(8) VALUE 'CSSEND '. 03 CSRECV PIC X(8) VALUE 'CSRECV '. 03 CSRLSE PIC X(8) VALUE 'CSRLSE '. 03 CSCONS PIC X(8) VALUE 'CSCONS '. 03 CSCONR PIC X(8) VALUE 'CSCONR '. 03 DSSEND PIC X(8) VALUE 'DSSEND '. 03 DSRECV PIC X(8) VALUE 'DSRECV '. 03 DSRLSE PIC X(8) VALUE 'DSRLSE '. 03 DSCONS PIC X(8) VALUE 'DSCONS '. 03 DSCONR PIC X(8) VALUE 'DSCONR '. 03 DSRCNS PIC X(8) VALUE 'DSRCNS '. 03 DSPRLS PIC X(8) VALUE 'DSPRLS '.

    36 VCOMPGM

  • 3.2 Fortran

    3.2.1 Parameter passingAll 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 onpage 89.

    For two specific parameters a structure is usually passed to VCOM.When writing a VCOM program in Fortran these structures are devidedinto several simple parameters. The parameters concerned are securityand receipt that are devided as follows:

    secur => seclen,secur

    receipt => rcpid,rcppart,rcprc,rcplth,rcpdata

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

    3.2.2 Interface codeTo be able to make use of the standard VCOM API module and to beable to load the VCOM API dynamically, the parameter list must beconstructed in a certain way. This is done by module called VCOMLFORthat must be linked together with the application itself.

    Language 37

  • 3.3 C

    3.3.1 Parameter passingAll calls to VCOM is of the type 'called by reference'. Example:

    cscons(&rc, &csid, &secur, &tmo, &sndtag, &prt, &init);

    More examples can be found in Appendix A. Program examples onpage 89.

    3.3.2 Include filesThe include files below are delivered with the VCOM software.

    38 VCOMPGM

  • /* * vcom.h *

    * Data structures, constants and function prototypes for * the VCOM API. *

    * The behavior of this file can be controlled by the following * macros: *

    * WINDOWS If you're building a Windows 3.x client, you must * define WINDOWS to get the corrent prototypes. * WIN32 Must be defined if you're building a client under * Windows 95 or Windows NT. * CLIENT All clients should define this to hide/show all * client specific definitions. * NO_PROTO If you're using an old K&R compiler, which doesn't * support function prototypes, define NO_PROTO. *

    */#ifndef VCOM_H#define VCOM_H

    /* * Vcom return codes */#include "rc.h"

    /* * Machine-independent type definitions */typedef short VcomInt16; /* 16-bit integer */typedef unsigned short VcomUInt16; /* 16-bit unsigned integer */#ifdef __osf__ /* DecUnix has 64-bit long */typedef int VcomInt32; /* 32-bit integer */typedef unsigned int VcomUInt32; /* 32-bit unsigned integer */#elsetypedef long VcomInt32; /* 32-bit integer */typedef unsigned long VcomUInt32; /* 32-bit unsigned integer */#endif

    /* CSID - Conversation ID */

    struct csid { char id 34;};

    typedef struct csid CSID;

    /* DSID - Distribution ID */

    struct dsid { char id 34;};

    typedef struct dsid DSID;

    Language 39

  • /* Structure to describe security info in connect calls */

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

    typedef struct secinfo SECINFO;

    /* Structure used to describe a receipt in DSCONS calls */

    struct receipt {char dsid 34; /* Original distid */char partner 8; /* Receiving partner */

    short rc; /* Return code: *//* 0 -- receipt always */

    VcomInt16 len; /* Length of receipt data *//* User data (if any) comes here */

    };

    typedef struct receipt RECEIPT;

    /* Prototype declarations of the VCOM API functions */

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

    40 VCOMPGM

  • extern void _zvfundecl cscons(VcomInt16 *retcode, CSID *csid,SECINFO *secinfo, VcomInt32 *timeout, char *sendertag,char *partner, char *initiator);

    extern void _zvfundecl csconr(VcomInt16 *retcode, CSID *csid,SECINFO *secinfo, VcomInt32 *timeout, char *sendertag,char *expediter, char *initiator);

    extern void _zvfundecl cssend(VcomInt16 *retcode, CSID *csid,VcomInt32 *length, void *data);

    extern void _zvfundecl csrecv(VcomInt16 *retcode, CSID *csid,VcomInt32 *timeout, VcomInt32 *maxlength,VcomInt32 *actlength, void *data);

    extern void _zvfundecl csrlse(VcomInt16 *retcode, CSID *csid);

    #ifdef CLIENTextern void _zvfundecl consrv(VcomInt16 *rc, char *server);extern void _zvfundecl discsrv(VcomInt16 *rc, char *server);extern VcomInt16 _zvfundecl dmpvcom(char *fileName);extern void _zvfundecl getvcomver(char **version);

    #endif

    extern void _zvfundecl dscons(VcomInt16 *retcode, DSID *dsid,SECINFO *secinfo, VcomInt32 *timeout, char *sendertag,char *partner, RECEIPT *receipt, char *prio,

    char *initiator);extern void _zvfundecl dsconr(VcomInt16 *retcode, DSID *dsid,

    SECINFO *secinfo, VcomInt32 *timeout, char *sendertag,char *expediter, char *rectype, char *initiator);

    extern void _zvfundecl dssend(VcomInt16 *retcode, DSID *dsid,VcomInt32 *length, void *data);

    extern void _zvfundecl dsrecv(VcomInt16 *retcode, DSID *dsid,VcomInt32 *maxlength, VcomInt32 *actlength,

    void *data);extern void _zvfundecl dsrlse(VcomInt16 *retcode, DSID *dsid, VcomInt16 *rvalue);extern void _zvfundecl dsrcns(VcomInt16 *retcode, DSID *dsid,

    SECINFO *secinfo, char *partner, char *initiator);extern void _zvfundecl dsprls(VcomInt16 *retcode, DSID *dsid);

    #ifndef CLIENTextern void _zvfundecl opercon(VcomInt16 *retcode, CSID *csid,

    VcomInt32 *timeout, char *network,char *node, char *initiator);

    extern void _zvfundecl opercmd(VcomInt16 *retcode, CSID *csid,VcomInt32 *timeout, VcomInt32 *clength,VcomInt32 *rmax, VcomInt32 *rlength,char *command, char *response);

    extern void _zvfundecl operrls(VcomInt16 *retcode, CSID *csid);#endif#if defined(__cplusplus)}#endif#else /* NO_PROTO */

    Language 41

  • extern void cscons();extern void csconr();extern void cssend();extern void csrecv();extern void csrlse();

    #ifdef CLIENTextern void _zvfundecl consrv();extern void _zvfundecl discsrv();extern VcomInt16 _zvfundecl dmpvcom();extern void _zvfundecl getvcomver();#endif

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

    #ifndef CLIENTextern void _zvfundecl opercon();extern void _zvfundecl opercmd();extern void _zvfundecl operrls();#endif

    #endif /* NO_PROTO */

    #endif /* VCOM_H */

    /** rc.h*

    * VCOM return codes*

    */

    #define VCOM_RC_SUCCESS 1 /* Universal success code */

    #define VCOM_RC_NORMAL 1 /* Normal release */#define VCOM_RC_REWIND_DS -1 /* Rewind a distribution */#define VCOM_RC_ROLLBACK -1 /* Synonym to _REWIND_DS */#define VCOM_RC_HOLD_DS -2 /* Hold a distribution */

    #define VCOM_RC_RLSE_SESS 35 /* Counterpart released session */#define VCOM_RC_NODISTR 41 /* No distribution found */#define VCOM_RC_DB_EOF 45 /* End of file */

    3.3.3 Interface codeTo be able to make use of the standard VCOM API module and to beable to load the VCOM API dynamically, the parameter list must beconstructed in a certain way. This is done by a very small module calledVCOMLC that must be linked together with the application itself.

    42 VCOMPGM

  • 3.4 REXXThe REXX programming language differs in several ways from otherprogramming languages such as Cobol. A special VCOM REXX api hastherefore been developed to define an easy and very REXX like way touse the VCOM verbs from the REXX language. The idea is that thisinterface should give the REXX programmer a way to use VCOM fol-lowing the REXX calling conventions. This means that the developershould not need to do any extra coding around the VCOM verbs whenusing them.

    3.4.1 Parameter passingThe arguments passed in the REXX verbs are only of type input. Thedata passed is always the data, not addresses or pointers.

    Output arguments are returned in standard output variables. These vari-ables are defined after a call to VCOM has been performed. The outputvariable names are built from a prefix concatenated with a specific outputparameter name.

    For an omitted parameter the following rules applies:

    1 Pass a comma with no previous argument to indicate that you arenot passing an argument.

    2 You can also pass a string containing no characters at all.

    3.4.2 Parameter descriptionThe following table describes the parameters used together with theVCOM API verbs.

    Name Type Descriptionprefix = 1 char Return code.

    Value set by VCOM after a verb has completed.

    Language 43

  • Name Type Descriptionconviddistid

    34 char-acters

    Session id for a conversation or a distribution.

    The conversation id or distribution id is assigned byVCOM after a connection has been established. Theid is 34 characters and has the following structure:

    net VCOM network name of initiator (8 charac-ters).

    node VCOM node name of initiator (8 characters).crtim session id time stamp in the format

    YYYYMMDDhhmmss (14 characters).seqnr session id sequence number (4 characters).

    secur 0..99characters

    Security information.

    The parameter can be used to exchange securityinformation. If the parameter is used, both the initi-ator and the responder must specify the same infor-mation in order to have a connection established.The parameter must either be specified by both sidesor be omitted by both sides.

    The security information can be up to 99 characterslong.

    Note that this parameter is translated by VCOM intothe character code appropriate for the environmentwhere the VCOM implementation is run. The validcharacter set to use is VCOM character set.

    timeout 1..8 char-acters

    Timeout value.

    The timeout value is specified in seconds and themaximum value that may be used is 365 days (cor-responding to a value of 31.536.000 seconds).

    sendertag 0..20characters

    Text string.

    The sendertag is any string that the sender wishesto send to the receiver in the connect phase.

    Note that this parameter is translated by VCOM intothe character code appropriate for the environmentwhere the VCOM implementation is run. The validcharacter set to use is VCOM character set.

    partner 1..8 char-acters

    Partner identification.

    This is the identification given by an initiator to indi-cate with whom a conversation is to be establishedor to whom a distribution is to be sent.

    expediter 1..8 char-acters

    Expediter identification.

    This is the identification given by a responder to in-form of the expediter name of the responding proc-ess.

    44 VCOMPGM

  • Name Type Descriptionrectype 1 charac-

    terReceive type.

    The receive type identifies the type of distribution thatis going to be received by a distribution responder.

    One of the following values are used:

    D Data. Used to indicate a normal data distribution.

    R Receipt. Used to indicate a receipt distribution.receipt character

    stringReceipt information.

    The receipt information is specified by the originatorof a distribution when the distribution is created.

    The receipt information has the following structure:

    distid id of the original distribution associatedwith the receipt.

    partner the partner name of the recipient.

    rc return code for the distribution associatedwith the receipt.

    length length of receipt data (16 bits). Maxlength is 256 bytes.

    data user receipt data. This is the receipt dataas specified by the originator of the as-sociated distribution when the distributionwas created.

    prio 1 charac-ter

    Distribution priority.

    The priority assigned a distribution by its originator.

    One of the following values may be used:

    N normal distribution priority.

    E express distribution priority.(c)(r)data character

    stringUser data area.

    Area containing user data to send or area into whichVCOM will deliver received data.

    (c)(r)length >= 0 char-acter

    Length of user data area.

    Length of user data area to send or length of inputarea to be used for receive.

    The maximum length is 9999 bytes.rvalue >= 1 char-

    acterReturn value.

    A return value given by a distribution sender or re-ceiver in a release request (DSRLSE) to indicate thefurther processing of the distribution by VCOM.

    Language 45

  • Name Type DescriptionInitiator 1..8 char-

    actersInitiator identification.

    This is the identification given by the primary side toindicate from whom a conversation request or a dis-tribution request originates.

    46 VCOMPGM

  • The following variables is set by the VCOM REXX api, they are not pre-fixed by the prefix name, described earlier.

    Name Type Descriptionvcomwork 4 charac-

    tersWork code, set by the VCOMINI verb.

    The code must be passed in all following VCOMverbs.

    result >= 1character(s)

    Result value (return code).The result code is set in the calling program if a verbis called as a subroutine.

    rc >= 1character(s)

    Rc, return code.

    The return code is set in the calling program if a verbis called as a function.

    Language 47

  • 3.4.3 API verb descriptionThe following pages describes each of the verbs provided by the VCOMREXX API.

    Each verb description also includes the parameters specific to that verb.After each parameter name is specified whether the parameter value isset by the application program or by VCOM. The notation i is used forinput parameters set by the application program before the verb is is-sued. The notation o is used for output parameters set by VCOM afterthe verb has completed.

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

    48 VCOMPGM

  • 3.4.5 InitialisationAdded to the commonly used VCOM verbs are two verbs only used bythe REXX api. These verbs are provided to setup and remove an envi-ronment used by the REXX api only.

    Before you are allowed to perform any CS or DS verbs you must do aVCOMINI call. This verb will declare and set a variable called 'vcomwork'.This name must be passed in all verbs following the 'VCOMINI' verb.When you have performed your last CS/DS verb you should release theenvironment by calling 'VCOMFIN'.

    Note: VCOMINI should be called only once at the beginning of a VCOMsession, VCOMFIN should be called only once at the end of a session.

    3.4.5.1 VCOMINI

    Verb: VCOMINI ()Description: The verb is used to initiate an api session. You are only

    allowed to perform this call once, before your first CSor DS verb.

    The following output parameters are set by the REXX interface. Theoutput names are not prefixed.

    vcomwork (o) work code. The string is set by VCOM/API at the com-pletion of the verb.

    The variable is four characters long and contains a bi-nary value. The code is only for internal use, the onlything you can do with it is to pass it to the api.

    3.4.5.2 VCOMFIN

    Verb: VCOMFIN (vcomwork)Description: The verb is used to terminate an api session. You are

    only allowed to perform this call once, after your last CSor DS verb.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    Language 49

  • 3.4.6 CSCONSVerb: CSCONS (vcomwork, prefix, secur, timeout, sendertag,

    partner, initiator)Description: The verb is used to initiate a conversation with a partner.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Themaximum length is 20 characters.

    The parameter is optional.

    secur (i) security information. A text string has to be given by theapplication program if a security check is to be madeagainst the partner program. If the parameter is omittedor empty, the specified partner must also use an omittedor empty security information parameter in order for aconnection to be established by VCOM.

    The parameter, if passed, should be a text string. Themaximum length of the string is 99 characters.

    The parameter is optional.

    timeout (i) timeout value in seconds. The string passed shouldcontain a numeric value.

    A positive value indicates the maximum time in secondsthat the initiator is prepared to wait for the conversationto be established.

    A negative value may be used to indicate that no time-out value is to be used, i.e. the initiator is prepared towait indefinitely for the conversation to be established.

    A value of zero may be used to indicate that the initiatorwill not wait for a conversation to be established but willonly accept a conversation if the conversation responderis immediately available. This is only applicable be-tween two partners in the same node.

    The parameter is a numeric string of 1 to 8 characters.

    The parameter is required.

    50 VCOMPGM

  • sendertag (i) sender information. The parameter is a string of char-acters that the initiator of the conversation wishes tosend to the conversation responder.

    The maximum length is 20 characters.

    The parameter is optional.

    partner (i) identification of the partner program. The string is usedby the application program to identify the partner proc-ess to which a conversation is requested.

    The parameter is a string of 1 to 8 characters.

    The parameter is required.

    initiator (i) identification of the initiator program. The parameter isused by the application program to identify the partnerprocess from whom the connect request originates.

    The parameter is a string of 1 to 8 characters.

    The parameter is optional.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. The string is set by VCOM/API at thecompletion of the verb.

    The variable is four characters long and contains nu-merics only.

    convid (o) conversation id. This is the identification of the conver-sation and this id must be used in all subsequent verbsissued to the same conversation. The string is set byVCOM/API at the completion of the verb if the returncode indicates that a conversation has been started.

    The parameter is a string of 34 characters.

    Language 51

  • 3.4.7 CSCONRVerb: CSCONR (vcomwork, prefix, secur, timeout, expediter)Description: The verb is used to respond to a conversation request

    from a partner program. The verb can also be used bya responder program to connect to VCOM in order toregister itself as an expediter even though no conver-sation requests currently are pending.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    secur (i) security information. A text string has to be given by theapplication program if a security check is to be madeagainst the partner program. If the parameter is omittedor empty, the specified partner must also use an omittedor empty security information parameter in order for aconnection to be established by VCOM.

    The parameter, if passed, should be a text string. Themaximum length of the string is 99 characters.

    The parameter is optional.

    timeout (i) timeout value in seconds. The string passed shouldcontain a numeric value.

    A positive value indicates the maximum time in secondsthat the responder is prepared to wait for a conversationto be established.

    A negative value may be used to indicate that no time-out value is to be used, i.e. the responder is preparedto wait indefinitely for a conversation request from apartner program.

    A value of zero may be used to indicate that theresponder will not wait for a conversation request butwill only accept a pending conversation request.

    The parameter is a numeric string of 1 to 8 characters.

    The parameter is required.

    52 VCOMPGM

  • expediter (i) identification of the responding program. This string isused by the application program in order to identify toVCOM the name of the expediter that is starting.

    The parameter is a string of 1 to 8 characters.

    The parameter is required.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. This variable is set by VCOM/API at thecompletion of the verb.

    The variable is four characters long and contains nu-merics only.

    convid (o) conversation id. This is the identification of the conver-sation and this id must be used in all subsequent verbsissued to the same conversation. The variable is setby VCOM/API at the completion of the verb if the returncode indicates that a conversation has been started.

    The parameter is a string of 34 characters.

    sendertag (o) sender information. This is a variable that will be set tothe value given to sendertag by the initiator when theconversation was started.

    The variable is 0 to 20 characters long information text.

    initiator (o) identification of the initiator program. The variable is setby the primary application program to identify the part-ner process from whom the connect request originates.

    The variable is 0 to 8 character long name.

    Language 53

  • 3.4.8 CSSENDVerb: CSSEND (vcomwork ,prefix, convid, length, data)Description: The verb is used to send data on a conversation to a

    partner program.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    convid (i) conversation id. This is the identification of the conver-sation on which the data is to be sent.

    The parameter is a string of 34 characters.

    The parameter is required.

    length (i) length information. The length parameter specifies theamount of data to send. The maximum length differsbetween the different enviroments. The parameter isoptional and the default length is set to the length of thedata string.

    The parameter is a numeric string of maximum 4 char-acters

    The parameter is optional.

    data (i) user data. User data that is to be sent on the conver-sation to the partner program.

    The parameter is an alphanumeric string.

    The parameter is required.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. This field is set by VCOM/API at the com-pletion of the verb.

    The variable is four characters long and contains nu-merics only.

    54 VCOMPGM

  • 3.4.9 CSRECVVerb: CSRECV (vcomwork, prefix, convid, timeout,

    maxlength)Description: 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 VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    convid (i) conversation id. This is the identification of the conver-sation 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 passedshould contain a numeric value.

    A positive value indicates the maximum time in secondsthat the responder is prepared to wait for data to arrive.If no data arrives within this time period, the receive re-quest will be completed with return codeVCOM_RC_TIMEOUT.

    A negative value may be used to indicate that no time-out value is to be used, i.e. the responder is preparedto wait indefinitely for data to arrive.

    A value of zero may be used to indicate that theresponder will not wait for data but will only accept datathat is pending on the conversation (i.e. polling). If nodata is present on the conversation, the receive requestwill be completed with return codeVCOM_RC_NODATA.

    The parameter is a numeric string of 1 to 8 characters.

    The parameter is required.

    maxlength (i) maximum length. The maximum length parameterspecifies the maximum amount of data that may be re-ceived in the data area. The parameter is optional and

    Language 55

  • is set to '9999' by default. The maximum length differsbetween the different environments.

    The parameter is a numeric string of maximum 4 char-acters

    The parameter is optional.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. This variable is set by VCOM/API at thecompletion of the verb.

    The variable is four characters long and contains nu-merics only.

    actlength (o) actual length. The actual length variable is set byVCOM at the completion of the verb and indicates theamount 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 recep-tion of data on the conversation to a partner program.

    The variable can contain any form of received data.

    56 VCOMPGM

  • 3.4.10 CSRLSEVerb: CSRLSE (vcomwork, prefix, convid)Description: The verb is used to terminate a conversation to a part-

    ner program.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    convid (i) conversation id. This is the identification of the conver-sation 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 outputname is prefixed by the prefix value passed through the verb.

    rc (o) return code. This variable is set by VCOM/API at thecompletion of the verb.

    The variable is four characters long and contains nu-merics only.

    Language 57

  • 3.4.11 DSCONSVerb: DSCONS (vcomwork, prefix, secur, timeout, sendertag,

    partner, receipt, prio, initiator)Description: The verb is used to initiate a distribution to a partner.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    secur (i) security information. The parameter is set by the appli-cation program if a security check is to be made againstthe partner program. If this parameter is omitted orempty, the specified partner must also use an omittedor empty security information parameter in order for adistribution to be delivered by VCOM to the partner.

    The parameter is a 0 to 99 bytes long alphanumericstring.

    The parameter is optional.

    timeout (i) timeout value in seconds. The parameter passedshould contain a numeric value.

    A positive value indicates the maximum time that mayflow before the distribution has been delivered to therecipient.

    A negative value indicates that no timeout is associatedwith the distribution.

    The value zero is not used.

    The parameter is a numeric string of 1 to 8 characters.

    The parameter is required.

    sendertag (i) sender information. The parameter contains any stringof characters that the sender of the distribution wishesto send to the distribution recipient.

    The data type is a 1 to 20 character long string.

    The parameter is optional.

    58 VCOMPGM

  • partner (i) identification of the partner program. The parameter isset by the application program to identify the partnerprocess to which the distribution shall be delivered.

    The parameter is 1 to 8 character long name.

    The parameter is required.

    receipt (i) receipt information. This data structure will be passedto the receipt recipient when a distribution has beendelivered to and accepted by its recipient or if timeoutoccurs.

    The parameter is a structured string described below.

    The parameter is optional.

    prio (i) distribution priority. The parameter specifies the re-quested priority for the distribution.

    The parameter is a one byte character code.

    The parameter is optional and if omitted, 'normal' prioritywill be used by VCOM.

    initiator (i) identification of the initiator program. The parameter isset by the application program to identify the partnerprocess from whom the distribution was delivered.

    The parameter is 1 to 8 character long name.

    The parameter is optional.

    The receipt information is a structured text string. The string can have alength between 13 and 269 characters depending on user data. Thestring contains the fields described below in that order.

    partner (i) identification of the receipt partner program. The fieldis set by the application program to identify the partnerprocess to which the receipt shall be delivered.

    The data type is a string of 8 bytes, padded with blanksif the name is shorter than eight characters.

    rc (i) selection of receipt processing. The field is set by theapplication program to indicate how VCOM is to handlethe receipt processing.

    The following values may be used:

    >0 indicates that the receipt always is to be deliv-ered to the receipt recipient.

  • The type is a numeric string of 5 bytes, padded withzeroes if the number is shorter than five characters.

    data (i) user data. User data to be included in the receipt.The type is an alphanumeric string.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. This variable is set by VCOM/API at thecompletion of the verb.

    The variable is four characters long and contains nu-merics only.

    distid (o) distribution id. This is the identification of the distributionand this id must be used in all subsequent verbs issuedto the same distribution. The variable is set byVCOM/API at the completion of the verb if the returncode indicates that a distribution has been started.

    The parameter is a string of 34 characters.

    60 VCOMPGM

  • 3.4.12 DSCONRVerb: DSCONR (vcomwork, prefix, secur, timeout, expediter)Description: The verb is used by an application program to identify

    itself to VCOM as a distribution receiver.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    secur (i) security information. The parameter is set by the appli-cation program if a security check is to be made againstthe partner program. If this parameter is omitted orempty, the initiating partner must also use an omittedor empty security information string in order for a dis-tribution to be delivered by VCOM to the partner.

    The parameter is a 0 to 99 characters long alphanu-meric string.

    The parameter is optional.

    timeout (i) timeout value in seconds. The parameter passedshould contain a numeric value.

    A positive value indicates the maximum time that theresponder is prepared to wait for a distribution to arrive.

    A negative value may be used to indicate that no time-out value is to be used, i.e. the responder is preparedto wait indefinitely for a distribution to arrive.

    A value of zero may be used to indicate that theresponder will not wait for a distribution arrival but willonly accept a pending distribution. If no distribution ispending, the request will be completed with the returncode VCOM_RC_NODISTR.

    The parameter is a numeric string of 1 to 8 bytes.

    The parameter is required.

    expediter (i) identification of the responding program. This parame-ter is set by the application program in order to identifyto VCOM the name of the expediter that is starting.

    Language 61

  • The parameter is 1 to 8 character long.

    The parameter is required.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. This variable is set by VCOM/API at thecompletion of the verb.

    The variable is four characters long and contains nu-merics only.

    distid (o) distribution id. This is the identification of the distributionand this id must be used in all subsequent verbs issuedto the same distribution. The variable is set byVCOM/API at the completion of the verb if the returncode indicates that reception of a distribution has beenstarted.

    The parameter is 34 character long.

    rectype (o) reception type. This variable is set by VCOM to indicatethe type of distribution to be delivered to the respondingprogram.

    The type is a character code.

    initiator (o) identification of the initiator program. The variable is setby the primary application program to identify the part-ner process from whom the distribution was delivered.

    The variable is 1 to 8 character long.

    sendertag (o) sender information. This is an variable that will be setto the value given to sendertag by the initiator when thedistribution was started.

    The value is 0 to 20 character long.

    62 VCOMPGM

  • 3.4.13 DSSENDVerb: DSSEND (vcomwork, prefix, distid, length, data)Description: The verb is used to send data on a distribution to a

    partner program. Note that the data transfer is a localprocess between the application program and the localVCOM node.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    distid (i) distribution id. This is the identification of the distributionon which the data is to be sent.

    The parameter is a string of 34 characters.

    The parameter is required.

    length (i) length information. The length parameter specifies theamount of data to send. The maximum length differsbetween the different environments.

    The parameter is optional and the length will be set tothe length of the data string by default.

    The parameter is a numeric string of maximum 4 char-acters.

    The parameter is optional.

    data (i) user data. User data that is to be sent on the distrib-ution to the partner program.

    The data type is a character string.

    The parameter is required.

    The following output parameters are set by the REXX interface. Theoutput names are prefixed by the prefix value passed through the verb.

    rc (o) return code. This variable is set by VCOM/API at thecompletion of the verb.

    Language 63

  • The variable is four characters long and contains nu-merics only.

    64 VCOMPGM

  • 3.4.14 DSRECVVerb: DSRECV (vcomwork, prefix, distid, maxlength)Description: The verb is used to receive data in a distribution from a

    partner program or to receive a receipt distribution.Note that the data transfer is a local process betweenthe application program and the local VCOM node.

    The following parameters are used:

    vcomwork (i) vcomwork is an environment code set by the VCOMINIverb.

    The parameter is required.

    prefix (i) Prefix name. The prefix is used to prefix the standardoutput names. If the parameter is omitted the defaultprefix will be 'VCOM'.

    The parameter, if passed, should be a valid name. Thename can contain a maximum of 20 characters.

    The parameter is optional.

    distid (i) distribution id. This is the identification of the distributionon which data is to be received.

    The parameter is a string of 34 characters.

    The parameter is required.

    maxlength (i) maximum length. The maximum length parameterspecifies the maximum amount of data that may be re-ceived in the data area. If the parameter is omitted thelength will be set to '9999'. The maximum length differsbetween the different environments.

    The parameter is a numeric string of maximum 4 char-acters.

    The parameter is optional.

    The following output parameters are set by the REXX interface. Theoutput names are pre


Recommended