unisys Distributed Processing Middleware Open Distributed Transaction Processing Administration Guide Volume 2: Building Applications

(1)

Distributed Processing Middleware

Open Distributed Transaction Processing

Administration Guide

Volume 2:

Building Applications

ClearPath OS 2200 Release 13.1

(2)

You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used.

The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions.

Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses.

Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Java EE and Java SE are trademarks of Oracle in the U.S. and other countries.

JBoss® is a registered trademark and JBoss Application Server™ is a trademark of Red Hat, Inc. and its subsidiaries in the U.S. and other countries.

All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.

(3)

Section 1. Getting Started 1.1. Documentation Updates ... 1–1 1.2. Purpose ... 1–1 1.3. Scope ... 1–2 1.4. Audience ... 1–2 1.5. Notation Conventions ... 1–2 1.6. Organization ... 1–3

Section 2. Open Distributed Transaction Processing Application Development

2.1. Classification of Application Programs ... 2–3 2.2. Open Group Communication Models ... 2–4 2.2.1. Request-Response Services ... 2–4 2.2.2. Conversational Services ... 2–4 2.3. Servers and Service Routines ... 2–4 2.3.1. Functions of a Server ... 2–6 2.3.2. Building a Server... 2–6 2.3.3. Order of Server Execution ... 2–7 2.3.4. Functions of a Service Routine ... 2–7 2.3.5. Types of Service Routines ... 2–7 2.4. Client Programs ...2–8 2.5. Communications Buffer Management ... 2–9 2.5.1. XATMI Calls for Application Programs ... 2–9 2.5.2. Buffer Types ... 2–10 2.5.3. Buffer Subtypes ... 2–10 2.6. Transaction Boundaries ... 2–11 2.6.1. Transaction Mode ... 2–11 2.6.2. AUTOTRAN Configuration... 2–11 2.7. API and Diagnostic Services Libraries ... 2–12 2.7.1. C Compiler XATMI Library ... 2–13 2.7.2. COBOL Compiler and ASCII COBOL Compiler

XATMI Libraries ... 2–14 2.7.3. JVM on OS 2200 XATMI Library ... 2–15 2.7.4. TX Libraries ... 2–16 2.7.5. Diagnostic Services Libraries ... 2–18

Section 3. Buffer Subtypes

3.1. Building VIEWs ... 3–2 3.1.1. Format of a VIEW ... 3–2

(4)

3.1.2. Corresponding COBOL Data Types for

X_COMMON and X_C_TYPE Buffer Types ... 3–4 3.1.3. Comments in a VIEW File ...3–5 3.1.4. Example of a VIEW File ...3–5 3.2. Using VIEW Utility Programs ... 3–6 3.2.1. Using the VADD Utility ... 3–6 3.2.2. Using the VDEL Utility ... 3–12 3.2.3. Using the VGET Utility ... 3–13 3.2.4. Using the View2java Compiler ... 3–15 3.3. Using BUFMAKE to Create a VIEW ... 3–31 3.3.1. Using the BUFMAKE Processor ... 3–32 3.3.2. VIEW Translation ... 3–36 3.3.3. Header Translation ... 3–37 3.3.4. Starting the BUFMAKE Processor ... 3–37 3.3.5. Example of BUFMAKE Execution ... 3–41 3.3.6. Comparing BUFMAKE and VADD ... 3–44

Section 4. Building Java Clients

4.1. Using the JMAC Utility ... 4–1 4.1.1. Procedures for Building Java Clients ... 4–3 4.1.2. Building the Make-Form Input ... 4–3 4.1.3. Calling the JMAC Utility ... 4–5 4.2. Example JMAC Call and Output ... 4–6

Section 5. Building Servers

5.1. Using the MAS Utility ... 5–2 5.1.1. Procedures for Building Servers ...5–3 5.1.2. Building the Make-Form Input ... 5–4 5.1.3. Calling the MAS Utility ... 5–9 5.2. MAS Examples ... 5–11 5.2.1. C and COBOL Example ... 5–11 5.2.2. Java Example ... 5–14 5.3. Starting Servers ... 5–21 5.3.1. Starting HVTIP and TIP Servers ... 5–21 5.3.2. Starting Batch Servers ... 5–21

Section 6. Extended Mode Servers

6.1. Building an Extended Mode HVTIP Server ... 6–2 6.1.1. Example MAS Call ... 6–3 6.1.2. Example MAKESERVER Addstream ... 6–4 6.1.3. Components of an Extended Mode HVTIP

Server ... 6–6 6.2. Building an Extended Mode TIP Server ... 6–7 6.2.1. Example MAS Call ... 6–8 6.2.2. Example MAKESERVER Addstream ... 6–9 6.2.3. Components of an Extended Mode TIP Server ... 6–11 6.3. Building an Extended Mode Batch Server ... 6–11

(5)

6.3.1. Example MAS Call ... 6–12 6.3.2. Example MAKESERVER Addstream ... 6–13 6.3.3. Components of an Extended Mode Batch

Server ... 6–15

Section 7. Basic Mode Servers

7.1. Building a Basic Mode HVTIP Server ... 7–1 7.1.1. Example MAS Call ... 7–3 7.1.2. Example MAKESERVER Addstream ... 7–4 7.1.3. Components of a Basic Mode HVTIP Server ... 7–7 7.2. Building a Basic Mode TIP Server ...7–8 7.2.1. Example MAS Call ... 7–10 7.2.2. Example MAKESERVER Addstream ... 7–11 7.2.3. Components of a Basic Mode TIP Server ... 7–13 7.3. Building a Basic Mode Batch Server ... 7–14 7.3.1. Example MAS Call ... 7–15 7.3.2. Example MAKESERVER Addstream ... 7–16 7.3.3. Components of a Basic Mode Batch Server ... 7–18

Section 8. Using Local Code to Modify Servers

8.1. Modifying Server Execution ... 8–1 8.2. C and Java Servers ...8–2 8.2.1. Modifying tpsvrinit() ...8–2 8.2.2. tpsvrinit() Example ... 8–3 8.2.3. Modifying tpsvrdone() ... 8–3 8.2.4. tpsvrdone() Example ... 8–3 8.3. COBOL Servers ... 8–3 8.3.1. TPSVRINIT Example ... 8–4 8.4. ASCII COBOL Servers ... 8–5 8.4.1. Modifying TPSVRINIT ... 8–5 8.4.2. Modifying TPSVRDONE ... 8–6

Section 9. Using the Security Service

9.1. Security Service Components ... 9–3 9.1.1. Operating System SESSION$CTRL Interface ... 9–3 9.1.2. The OCMS Activity ... 9–3 9.1.3. Open Distributed Transaction Processing

Session Manager Subsystem Component ... 9–3 9.1.4. Open Distributed Transaction Processing

Security Service Template Code ... 9–4 9.1.5. Transaction Integrator Security Gateway and

HTML Templates ... 9–4 9.2. Functional Overview ... 9–4 9.3. Security Service Processing ... 9–7 9.3.1. Using a Generic Buffer ... 9–7 9.3.2. Processing a New Password ... 9–7 9.4. Environment Requirements... 9–8

(6)

9.5. Open Distributed Transaction Processing

Configuration Requirements ... 9–9 9.5.1. MAX_THREADS... 9–9 9.5.2. User Log ... 9–9 9.5.3. PID Pool... 9–9 9.5.4. TD_CNV_TIME (UnixWare Environment Only) ... 9–10 9.6. Dependencies ... 9–10 9.6.1. Managing Throughput ... 9–10 9.6.2. Handling Passwords and New Passwords ... 9–11 9.6.3. ELMS Messages ... 9–11 9.7. Operations ... 9–11 9.7.1. Open CMS (OCMS) Activity ... 9–11 9.7.2. TSF Processor ... 9–12 9.7.3. TD2200 (UnixWare Environment Only) ... 9–12 9.8. Administration ... 9–12 9.8.1. Building Headers and Installing VIEWs ... 9–12 9.8.2. Building the Security Server ... 9–12 9.8.3. Updating the TMSCONFIG File ... 9–13 9.8.4. Securing the User Log File ... 9–13 9.9. Transaction Integrator Considerations ... 9–14 9.10. Customization Considerations ... 9–14 9.10.1. Database Logging... 9–14 9.10.2. Session Timeout Optimization ... 9–15 9.10.3. Non-Internet-Based Client Development ... 9–15 9.10.4. End Service Programming... 9–15 9.10.5. Message Logging ... 9–15 9.11. Security Service Template Code ... 9–15 9.12. Security Service VIEWs ... 9–32 9.12.1. VIEW secsvc_view ... 9–32 9.12.2. VIEW retmsg ... 9–33 9.13. Message Logging ... 9–38 9.13.1. LLMS Return Status ... 9–39 9.13.2. SESSION$CTRL ROQ Return Status ... 9–41

Appendix A. Restrictions, Operational Considerations, and Compatibility

A.1. Restrictions ... A–1 A.2. Operational Considerations ... A–2 A.2.1. Unsupported TX Calls... A–2 A.2.2. COMP-5 Usage ... A–2 A.2.3. Advertising Services... A–2 A.3. Compatibility with Other Products or System

Software ... A–2 A.3.1. Compatibility with Runtime System for

Extended Mode Compilers ... A–2 A.3.2. Compatibility with Unisys OS 2200 OSI-TP

High-Performance Transaction Processing for

XATMI (HTP/x) ... A–2 A.3.3. Compatibility with Open Distributed

(7)

A.3.4. Compatibility with Open Distributed

Transaction Processing Level 8R1 ... A–3 A.3.5. Compatibility with Open Distributed

Transaction Processing level 9R1 ... A–3

Appendix B. Thread-Control Commands

B.1. OS 2200 Universal Data System (UDS) ... B–1 B.2. File Control Superstructure (FCSS) ... B–1 B.3. XA and Universal Database Control Functions ... B–2 B.4. TX and Step Control ... B–3 B.5. Step Control for Nonglobal Transactions ... B–4

Appendix C. Java Package Contents

C.1. TransactionTP Contents ... C–1 C.2. TransactionView Interface Contents ... C–8

Glossary ... 1 Index ... 1

(8)

(9)

Figures

2–1. Client Calling a Server ... 2–3 2–2. Structure of a C or COBOL Server ... 2–5 2–3. Structure of a Java Server ... 2–5 3–1. Using the VADD Utility ... 3–11 3–2. Using the VGET Utility ... 3–15 3–3. BUFMAKE and VADD Processors and the Open Distributed

Transaction Processing FGSS ... 3–45 9–1. Security Service Functional Overview ... 9–5

(10)

(11)

Tables

2–1. Server Programming Options ...2–8 2–2. Open Group Typed Buffers Supported by Open Distributed

Transaction Processing ... 2–10 2–3. Communications Functions in the C Compiler XATMI Library ... 2–13 2–4. Buffer Management Functions in the C Compiler XATMI Library ... 2–13 2–5. Service Advertisement Functions in the C Compiler XATMI Library ... 2–14 2–6. Communications Routines in the COBOL Compiler XATMI Libraries ... 2–14 2–7. Service Initialization Routine in the COBOL Compiler XATMI Libraries ... 2–15 2–8. Service Advertisement Routines in the COBOL Compiler XATMI

Libraries ... 2–15 2–9. Communications Functions in the JVM on OS 2200 XATMI Library ... 2–15 2–10. Buffer Management Functions in the JVM on OS 2200 XATMI Library ... 2–16 2–11. C Compiler TX Library Functions ... 2–16 2–13. COBOL Compiler TX Library Routines ... 2–17 2–14. JVM on OS 2200 TX Library Functions ... 2–17 2–15. C Compiler Diagnostic Services Library Functions ... 2–18 2–16. COBOL Compiler Diagnostic Service Library Routines ... 2–18 3–1. Data Type Translation: Server Perspective ... 3–36 3–2. Data Type Translation: Client Perspective ... 3–37 3–3. BUFMAKE Processor Commands and Command Parameters ... 3–38 3–4. BUFMAKE Command Parameters and Values... 3–39 3–5. Additional Data Fields That Precede User Data Fields ... 3–43 4–1. Steps to Build a Client ... 4–3 4–2. Make-Form Parameter Values ... 4–4 5–1. Steps to Build a Server ...5–3 5–2. Make-Form Parameter Table Values ...5–5 5–3. Make-Form File Table Value ... 5–6 6–1. Extended Mode HVTIP Server Components ... 6–6 6–2. Extended Mode TIP Server Components ... 6–11 6–3. Extended Mode Batch Server Components ... 6–15 7–1. Basic Mode HVTIP Server Components ... 7–7 7–2. Basic Mode TIP Server Components ... 7–13 7–3. Basic Mode Batch Server Components ... 7–18 9–1. LLMS System Error Returns ... 9–39 9–2. LLMS Illegal Character Returns ... 9–40 9–3. ROQ Success Status Returns ... 9–41

(12)

9–4. ROQ User-Related Failure Status Returns ... 9–42 9–5. ROQ System Failure Status Returns ... 9–43 B–1. Mapping of XA Functions to Universal Database Control Functions ... B–2 B–2. Mapping of TX Functions to Step Control Actions for RMs ... B–3

(13)

Examples

3–1. Example VIEW File ...3–5 3–2. VADD Call ... 3–8 3–3. View Input File ... 3–9 3–4. C Include Element ... 3–9 3–5. COBOL COPY Elements ... 3–10 3–6. VDEL Call ... 3–12 3–7. VGET Call... 3–15 3–8. Open Distributed Transaction Processing VIEW File and Java Source

File ... 3–31 3–9. BUFMAKE Execution ... 3–42 3–10. BUFMAKE Input ... 3–42 3–11. BUFMAKE VIEW ... 3–44 4–1. JMAC Call ... 4–7 4–2. MAKECLIENT Addstream ... 4–9 5–1. C and COBOL MAS Call ... 5–12 5–2. C and COBOL MAKESERVER Addstream ... 5–13 5–3. Java MAS Call ... 5–15 5–4. Java MAKESERVER Addstream ... 5–18 6–1. MAS Input for a COBOL HVTIP Server ... 6–3 6–2. MAKESERVER Addstream for a COBOL HVTIP Server ... 6–6 6–3. MAS Input for a COBOL TIP Server ... 6–9 6–4. MAKESERVER Addstream for a COBOL TIP Server... 6–11 6–5. MAS Input for a COBOL Batch Server ... 6–12 6–6. MAKESERVER Addstream for a COBOL Batch Server ... 6–14 7–1. MAS Input for an ASCII COBOL HVTIP Server ... 7–4 7–2. MAKESERVER Addstream for an ASCII COBOL HVTIP Server ... 7–6 7–3. MAS Input for an ASCII COBOL TIP Server ... 7–10 7–4. MAKESERVER Addstream for an ASCII COBOL TIP Server ... 7–13 7–5. MAS Input for an ASCII COBOL Batch Server ... 7–15 7–6. MAKESERVER Addstream for an ASCII COBOL Batch Server ... 7–18 8–1. tpsvrinit() Routine ... 8–3 8–2. tpsvrdone() Routine ... 8–3 8–3. TPSVRINIT Routine... 8–4 8–4. TPSVRDONE Routine ... 8–5 8–5. Default TPSVRINIT Routine ... 8–6 8–6. Default TPSVRDONE Routine ... 8–6

(14)

9–1. Security Service Template Code ... 9–17 9–2. VIEW secsvc_view ... 9–33 9–3. View retmsg ... 9–33 9–4. Security Service Message Header ... 9–35

(15)

Distributed Processing Middleware Open Distributed Transaction Processing (formerly known as Open/OLTP) software is the Unisys implementation of The Open Group Distributed Transaction Processing (DTP) model. (The Open Group was formerly known as X/Open.) Open Distributed Transaction Processing provides an open, standards-compliant environment for developing DTP applications, including global transactions. The DTP environment can include the following systems:

• OS 2200 operating environment of ClearPath IX servers

• MCP operating environment of ClearPath NX servers

• Microsoft Transaction Server (MTS) operating environment

This document describes how to build Open Distributed Transaction Processing applications for OS 2200 operating environment.

1.1. Documentation Updates

This document contains all the information that was available at the time of

publication. Changes identified after release of this document are included in problem list entry (PLE) 18820731. To obtain a copy of the PLE, contact your Unisys

representative or access the current PLE from the Unisys Product Support Web site: http://www.support.unisys.com/all/ple/18820731

Note: If you are not logged into the Product Support site, you will be asked to do

so.

1.2. Purpose

This guide (previously titled OS 2200 Open/OLTP Transaction Manager [OLTP-TM2200] Administration Guide Volume 2) describes Open Distributed Transaction Processing. It includes information about performing the following procedures in the OS 2200 operating environment:

• Installing and managing buffer subtypes, used to structure data exchanged between application programs.

• Building and installing servers that provide access to service routines from Open Distributed Transaction Processing user application programs.

(16)

1.3. Scope

Procedures for most system administration tasks provide detailed explanations of syntax and options for utilities, runstreams, and programs. Examples include runstreams that can be used with minor changes, as well as programs that demonstrate software features such as function calls. This guide also provides conceptual background and guidelines for effective Open Distributed Transaction Processing system administration.

System administration tasks not covered in this guide are described in the Open Distributed Transaction Processing Administration Guide Volume 1.

1.4. Audience

This guide is for Open Distributed Transaction Processing system administrators who are responsible for

• Installing and managing Open Distributed Transaction Processing and user applications software in the OS 2200 operating environment

• Building servers that provide access to OS 2200 service routines from client programs

• Working with programmers and administrators to design and administer Open Distributed Transaction Processing applications

• Working with OS 2200 operations personnel to maintain Open Distributed Transaction Processing operations

This information may also be used by applications programmers under the direction of system administrators.

1.5. Notation Conventions

This guide uses the following notation conventions.

Item Examples

Variable names

Variable names are intended to be replaced by actual names. They appear as follows:

error-file-name

The when-return value Function

names in text

C uses lowercase, parentheses, and possibly underscores for function names, as follows: tpcall(), tx_begin()

COBOL uses uppercase for function (subprogram) names without underscores, hyphens, or parentheses, as follows: TPCALL, TXBEGIN Java™ uses mixed case (case sensitive) and parentheses for method names, as follows: getReply()

(17)

Item Examples Symbolic constants (keywords, error codes, and flags)

C uses uppercase and possibly underscores in symbolic constants, as follows: TPSUCCESS, TPEV_SVCERR

COBOL uses uppercase and possibly hyphens in symbolic constants, as follows: TPSUCCESS, TPEV-SVCERR

Java uses uppercase and possibly underscores in symbolic constants, as follows: TPSUCCESS, TX_UNCHAINED

Syntax C synopsis:

char * tpalloc (char *type, char *subtype, long size); COBOL statement:

CALL “TPDISCON” USING TPSVCDEF-REC TPSTATUS-REC.

Note: Use single or double quotation marks as required by the compiler.

Java synopsis:

static int acall (java.lang.String service, TransactionTP.Buffer buffer, long bufferLength) ;

Ellipsis (…) An ellipsis in examples indicates code that is omitted because it is not pertinent to the discussion.

Brackets […]

Items in brackets indicate optional entries that you can use or omit. They appear as follows:

[APNAME apname]

Braces {…} Items in braces indicate choices from which you must include one. They appear as follows:

{EXTENDED  BASIC} Vertical bar

 Vertical bars separate multiple options enclosed by brackets or braces. They appear as follows: {EXTENDED  BASIC)

1.6. Organization

This guide consists of the following sections and appendixes:

Section 1. Getting Started

This section.

Section 2. Open Distributed Transaction Processing Application Development

This section presents concepts about application development and transaction management in the Open Distributed Transaction Processing environment.

(18)

Section 3. Buffer Subtypes

This section describes the structure and use of buffer subtypes, used to exchange data between application programs. It also explains how to install and delete buffer subtypes using Open Distributed Transaction Processing utilities.

Section 4. Building Java Clients

This section describes the JMAC utility, which creates an addstream used to build a client.

Section 5. Building Servers

This section describes the MAS utility, which creates an addstream used to build a server.

Section 6. Extended Mode Servers

This section describes considerations for building HVTIP, TIP, and batch servers for an extended mode environment.

Section 7. Basic Mode Servers

This section describes considerations for building HVTIP, TIP, and batch servers for a basic mode environment.

Section 8. Using Local Code to Modify Servers

This section describes how you can use local code to modify the execution of the server main program by creating your own versions of the tpsvrinit() initial processing routine and tpsvrdone() final processing routine.

Section 9. Using the Security Service

This section describes the Open Distributed Transaction Processing security service, which provides secure access to Open Distributed Transaction Processing server transactions from the Internet. The security service is a template you can use as is or modify to suit your needs. The source code for the service, VIEWs, and error

messages is provided.

Appendix A. Restrictions, Operational Considerations, and Compatibility

This appendix lists temporary and permanent operating limitations, as well as compatibility issues with other system products.

Appendix B. Thread-Control Commands

This appendix lists Universal Data System thread-control commands used by the Open Distributed Transaction Processing system.

Appendix C. Java Package Contents

(19)

Processing Application Development

Distributed Processing Middleware Open Distributed Transaction Processing (formerly known as Open/OLTP) software is the Unisys implementation of the Open Group Distributed Transaction Processing (DTP) model. (The Open Group was formerly known as X/Open.) Open Distributed Transaction Processing provides an open, standards-compliant environment for developing DTP applications, including global transactions. The DTP environment can include the following systems:

• OS 2200 operating environment of ClearPath IX servers

• Systems of other vendors that support the Open Group standards, such as TUXEDO

This section summarizes Open Distributed Transaction Processing application development, as well as transaction management concepts and topics described in more detail in other documents. It provides system administrators with background information needed to perform the tasks described in this guide.

This section describes

• How Open Distributed Transaction Processing conforms to the Open Group Distributed Transaction Processing (DTP) model

• Components of a DTP application

• Application development concepts and tools

The following terms related to transactions are used frequently in this and other Open Distributed Transaction Processing guides.

A transaction

is a complete unit of work that maintains the ACID (atomicity, consistency, isolation, and durability) properties for the work it performs. Typically, a

transaction updates one or more databases. In distributed transaction processing (DTP), a transaction can include multiple units of work performed on one or more systems.

(20)

A global transaction

is a transaction in which the work is distributed over multiple application programs and resource managers, possibly on multiple machines. An application program defines the start and end of a global transaction. A transaction manager

coordinates the initiation and completion of a global transaction (on behalf of an application program) by communicating with participating resource managers. Transaction mode

is a mode of execution for an application program in which the application program is performing work under the control of a transaction manager. The transaction manager controls initiation and completion of the transaction and issues all necessary thread-control commands.

A nonglobal transaction

is work performed by a single application program thread of control, not under the control of a transaction manager. In a nonglobal transaction, one or more resource managers (RM) are defined to the application program, but not to the transaction manager. Application programs (AP) commit work that resource managers perform using native AP-RM interface commands, such as SQL COMMIT. This section contains the following topics.

Topic Description Reference

Classification of

application programs Client and server programs 2.1 Open Group

communication models

Request/response and conversational services communication models

2.2

Servers and service routines

Components and functions of a server; order of server execution; service routines

2.3 Client programs Client program characteristics and use 2.4 Communications

buffer management Open Distributed Transaction Processing buffers; typed buffers; supported buffer types

2.5

Transaction

boundaries Transaction Demarcation (TX) calls; transaction mode (AUTOTRAN) configuration 2.6 API and diagnostic

services libraries

Open Group Application to Transaction Manager (XATMI) and TX library application program interfaces (API); diagnostic services libraries

(21)

For more information about Open Distributed Transaction Processing application development, see these documents:

• Open Distributed Transaction Processing TX Application Program Interface Programming Guide

• Open Distributed Transaction Processing XATMI Application Program Interface Programming Guide

• Open Distributed Transaction Processing Programming Guide

2.1. Classification of Application Programs

Application programs are classified as one of the following:

• Client programs

• Servers (with their associated service routines)

An application program that requests a service is called a client. Client programs gather data from end users and call services to access databases and other resources. (Service routines can also act as clients when they call other service routines to

request services.) For additional information about client programs, see 2.4. An application program that provides the service for a client is called a server. A server consists of a main program and one or more service routines. Servers call service routines and send replies back to clients. A server also calls the transaction manager to handle transaction commitment with a resource manager, such as a database. For additional information about servers, see Section 5.

Each service routine is associated with a server. You associate service routines with servers when you build server programs.

The following illustration shows a client program requesting a service from a server. The server calls the service routine that provides the requested service.

Figure 2–1. Client Calling a Server

C li e n t P ro g r a m Requ es t Re spo ns e Se r v e r P ro g r a m Se rv i c e R o u ti n e A Se rv i c e R o u ti n e B Se rv i c e R o u ti n e C

(22)

2.2. Open Group Communication Models

Open Distributed Transaction Processing supports both of the following communication models from The Open Group (formerly known as X/Open):

• A request-response services communication model based on service requests

• A conversational service communications model based on the exchange of messages

2.2.1. Request-Response Services

In request-response communication, client programs do not establish connections with service routines. Instead, clients send requests to Open Distributed Transaction Processing communication resource managers (CRM) and either wait for or ask for service routine replies. A client that waits for a service routine reply communicates synchronously; a client that makes a request, performs other work, and later asks for a reply communicates asynchronously.

Unlike a traditional OS 2200 transaction program, the service routine usually does not commit the work on its own. Instead, it relies on Open Distributed Transaction Processing to perform the database commitment or rollback.

2.2.2. Conversational Services

In conversational communication, client programs establish logical connections with service routines (through Open Distributed Transaction Processing CRMs) and conduct dialogues. Dialogues occur as one program sends data and the other receives data. During conversations, clients and service routines can exchange the sending and receiving roles.

2.3. Servers and Service Routines

Servers consist of the following components:

• Server main program

• The tpsvrinit() initial processing routine

• One or more service routines

• The tpsvrdone() final processing routine

The server main program interfaces with the transaction manager and the communication resource manager (CRM). As part of initialization, the server main program calls the tpsvrinit() initial processing routine. The server main program can then accept service requests and call the appropriate service routine to handle the request. Before the server terminates, the server main program calls the tpsvrdone final processing routine.

(23)

The following illustration shows the general structure of an Open Distributed Transaction Processing server program for the C Compiler and COBOL Compiler. All components except the server main program are coded by the Open Distributed Transaction Processing applications developer.

Figure 2–2. Structure of a C or COBOL Server

The following illustration shows the general structure of an Open Distributed Transaction Processing server program for Virtual Machine for Java Platform on ClearPath OS 2200. All components except the server main program are coded by the Open Distributed Transaction Processing applications developer.

Note: Multiple services within a routine are not allowed for Virtual Machine for

Java Platform on ClearPath OS 2200.

Figure 2–3. Structure of a Java Server

service_routine n service_routine2 tpsvrinit main tpsvrdone service_routine1 service_a service_b

Predefined server module

Server Service Routines tpsvrinit main tpsvrdone service_routinen service_routine2 service_routine1

(24)

2.3.1. Functions of a Server

Servers are application programs that offer services to clients. The services are implemented as service routines. C Compiler and COBOL Compiler can implement more than one service in each service routine. However, when the service routine is called by the server main program, the service routine performs only one of its services and then returns to the server main program.

Note: Multiple services within a routine are not allowed for Virtual Machine for

Java Platform on ClearPath OS 2200.

The functions of a server are to

• Interface with the transaction manager

• Accept service requests

• Invoke the appropriate service routine to perform the service

You can use local code to modify how your server initializes and terminates. For more information, see Section 8.

2.3.2. Building a Server

Open Distributed Transaction Processing servers consist of both

• Components that you define and build

• Standard components (provided with Open Distributed Transaction Processing) that you cannot modify

Open Distributed Transaction Processing provides the MAS utility that you can use to build and link a server. The MAS utility creates an addstream of Executive Control Language (ECL) commands to make a server. The addstream contains the

• Statements that create the necessary server components

• Static linking commands to link the server

You can build Open Distributed Transaction Processing servers as batch, TIP, or HVTIP servers in either the basic or extended mode execution environment. You can use the MAS utility to build servers in C Compiler, COBOL Compiler, ASCII COBOL Compiler, or JVM on OS 2200 versions. All of the service routines associated with any one server must be coded using the same language.

(25)

2.3.3. Order of Server Execution

A server is executed in this order: 1. Initialize.

The tpsvrinit initial processing routine initializes a server. You can supply your own version of the tpsvrinit routine. (The default version performs no processing, but simply returns.)

2. Accept service requests.

The server then calls service routines to perform the requested services. A server can provide one or many services before terminating.

3. Terminate.

The tpsvrdone routine performs final processing before a server terminates. You can supply your own version of the tpsvrdone routine. (The default version performs no processing, but simply returns.)

2.3.4. Functions of a Service Routine

Service routines are application programs that perform the application-specific processing requested by client programs (or other service routines acting as clients). A service routine typically

• Receives service request parameters and control from a server

• Processes a service

• Returns control to the server

For more information about service routines, refer to

• Open Distributed Transaction Processing Administration Guide Volume1

2.3.5. Types of Service Routines

Open Distributed Transaction Processing supports servers and service routines for both extended mode and basic mode for OS 2200 transaction and batch execution modes. The following table summarizes the programming and execution options for servers and their associated service routines.

(26)

Table 2–1. Server Programming Options Execution Mode Extended Mode Programming Basic Mode Programming High-Volume Transaction

Processing (HVTIP) C Compiler _{COBOL Compiler} ASCII COBOL Compiler Transaction Processing (TIP) C Compiler

COBOL Compiler

ASCII COBOL Compiler

Batch C Compiler

COBOL Compiler Virtual Machine for the Java Platform onClearPath OS 2200

ASCII COBOL Compiler

A server can call any service routine programs associated with it. Each service routine name is unique to the Open Distributed Transaction Processing installation.

Service routines can be coded using either C Compiler, COBOL Compiler, ASCII COBOL Compiler, or Virtual Machine for the Java Platform on ClearPath OS 2200. All of the service routines associated with one server must be coded in the same language. Service routine coding must conform to a strict format in order to be called successfully by the server main program. See the Open Distributed Transaction Processing Programming Guide for information about the coding format.

2.4. Client Programs

Client programs typically handle a user interface. They accept input and display the results of the transaction. A client program can initiate a transaction that involves one or more units of work. A client program can also initiate multiple transactions.

Client programs rely on service routines to perform the work associated with the transaction, such as querying and updating databases. The request for service is routed through Open Distributed Transaction Processing to the server that owns the service routine. The server then calls the service routine.

Open Distributed Transaction Processing allows client programs to access their own resource managers and optionally include the access as part of the transaction. For example, a client could use the Message Control Bank (MCB) as a resource manager for handling terminal messages.

A service routine can act like a client and request services, but a client program cannot offer services.

(27)

Client programs that request services from Open Distributed Transaction Processing can execute on

• The same OS 2200 operating environment of ClearPath IX servers

• Other OS 2200 operating environments of ClearPath IX servers

• The same OS 2200 Open Distributed Transaction Processing system

• Other OS 2200 Open Distributed Transaction Processing systems

• MCP Open Distributed Transaction Processing systems

• Systems of other vendors that support the Open Group standards, such as TUXEDO and TUXEDO /WS for workstations

Client programs are completely user written. The programs do not have to conform to a particular format. For additional information about client programs, see the

• Open Distributed Transaction Processing TX Application Program Interface Programming Guide

• Open Distributed Transaction Processing XATMI Application Program Interface Programming Guide

2.5. Communications Buffer Management

Open Distributed Transaction Processing maintains and manages its own

communications buffers to exchange data among programs. It also provides a set of XATMI buffer functions that C language application programs call to obtain, expand, and free typed communications buffers. For a list of buffer management functions, see 2.7.

Any data passed between a C or Java client and a server must be placed in a typed buffer (record) obtained from Open Distributed Transaction Processing. Attempts to pass data using a declared buffer or one created with the malloc() function fails. Because COBOL does not support pointers and dynamic memory, COBOL programs cannot dynamically allocate typed buffers (records) for communications. Instead, COBOL programs must define storage for buffer data and inform Open Distributed Transaction Processing what the buffer type and subtype are when the buffer data is used.

2.5.1. XATMI Calls for Application Programs

To send data between application programs, the sending application program first puts the data in a buffer (record). A typed buffer contains data and has associated with it a type and possibly a subtype that indicate the meaning or interpretation of the data. Typed buffers are dynamically allocated.

(28)

2.5.2. Buffer Types

Open Distributed Transaction Processing software uses Open Group XATMI typed buffers and user-defined buffer subtypes to define data structures, as shown in the following table. These structures ensure that application programs can successfully exchange data, even when they reside on different types of machines.

Table 2–2. Open Group Typed Buffers Supported by Open Distributed Transaction Processing

Typed Buffer Function

X_OCTET The X_OCTET typed buffer is an array of bytes (characters). The contents of an X_OCTET typed buffer are completely defined by the application. This typed buffer is used for application programs that internally define the structure of the data to be exchanged. X_COMMON An X_COMMON typed buffer is a nonnested C structure, COBOL

record, or Java class, whose elements are any of these C or associated java data types: short, long or char. You must define and install your own buffer subtypes before you can use X_COMMON buffers. Once these buffer subtypes are installed, Open Distributed Transaction Processing encodes and decodes them on behalf of the APs.

X_C_TYPE An X_C_TYPE typed buffer is a nonnested C structure, COBOL record, or Java class, whose elements are any of these C or associated Java data types: int, short, long, char, float, double, character string, and octet array. You must define and install your own buffer subtypes before your APs can use X_C_TYPE buffers. Once these buffer subtypes are installed, Open Distributed Transaction Processing encodes and decodes them on behalf of the APs.

2.5.3. Buffer Subtypes

If you use the X_C_TYPE or X_COMMON buffer types, you must define and install buffer subtypes before the buffers can be used successfully by application programs to exchange data. Buffer subtypes describe the structure and meaning of the data placed in typed buffers. (The X_OCTET buffer type does not allow a buffer subtype.) You install buffers by using the VADD utility to store buffer subtype definitions in the type directory. Once these buffer subtypes are installed, Open Distributed Transaction Processing encodes and decodes the buffer data on behalf of the application

programs.

(29)

2.6. Transaction Boundaries

Programmers use the TX services library to control transaction boundaries. The TX services library contains routines defined by the Open Group Transaction Demarcation (TX) specification. TX routines

• Begin transactions explicitly

• End transactions by either

− Committing the work done by the transaction

− Rolling back (aborting) the work done by the transaction

See 2.7.4 for lists of the TX routines available for C, COBOL, and Java application programs.

2.6.1. Transaction Mode

When an application program performs work under the control of a transaction manager, it is said to be in transaction mode. A client program enters transaction mode when it calls the tx_begin() function. A service routine called by a client as part of a global transaction is also in transaction mode.

2.6.2. AUTOTRAN Configuration

In some cases, a service routine is implicitly placed in transaction mode even though it was not called in transaction mode. This occurs if the service is configured to execute automatically in transaction mode (AUTOTRAN). The AUTOTRAN switch is set in the *SERVICES section of the TMSCONFIG file; see the Open Distributed Transaction Processing Administration Guide Volume 1 for information.

Before the service routine is called, Open Distributed Transaction Processing calls tx_begin(). When the service completes, Open Distributed Transaction Processing calls tx_commit(); and the reply is sent after the commitment completes.

If the service returns to the server main program with a fail status (TPFAIL), Open Distributed Transaction Processing calls tx_rollback() to roll back the transaction instead.

(30)

2.7. API and Diagnostic Services Libraries

Open Distributed Transaction Processing provides libraries that include

• XATMI services

Includes the set of XATMI functions as defined by Open Group

• TX services

Includes the set of TX functions as defined by Open Group

• Diagnostic services

Includes functions that provide run-time diagnostic information and allows programs to log diagnostic information to the Open Distributed Transaction Processing event log

All services are available for programming in

• C Compiler

• COBOL Compiler

• ASCII COBOL Compiler

• JVM on OS 2200 (diagnostic services not available) This subsection contains the following topics.

C Compiler XATMI

library Communications functions; buffer management functions; service advertisement functions

2.7.1

COBOL Compiler and ASCII COBOL Compiler XATMI libraries

Communications routines; service

initialization routines; service advertisement routines

2.7.2

JVM on OS 2200

XATMI library Communications functions; buffer management functions 2.7.3 TX libraries C Compiler, COBOL Compiler, ASCII COBOL

Compiler, and JVM on OS 2200 routines 2.7.4 Diagnostic services

libraries

C Compiler, COBOL Compiler, and ASCII COBOL Compiler diagnostic services routines

(31)

2.7.1. C Compiler XATMI Library

The following table lists the communications functions in the C Compiler XATMI library.

Table 2–3. Communications Functions in the C Compiler XATMI Library

Function Description

tpacall() Sends an asynchronous service request tpcall() Sends a service request and waits for the reply tpcancel() Cancels a call descriptor

tpconnect() Establishes a conversational service connection tpdiscon() Aborts a conversational service connection

tpgetrply() Receives a reply to an asynchronous service request tprecv() Receives a conversational message

tpreturn() Returns from a service routine and sends the reply tpsend() Sends a conversational message

The following table lists the buffer management functions in the C Compiler XATMI library.

Table 2–4. Buffer Management Functions in the C Compiler XATMI Library

tpalloc() Allocates a typed buffer of a specified type and subtype tpfree() Releases a typed buffer

tprealloc() Changes the size of a typed buffer

tptypes() Determines the type, subtype, and size of the buffer when called by an application program that receives a typed buffer

(32)

The following table lists the service advertisement functions in the C Compiler XATMI library.

Table 2–5. Service Advertisement Functions in the C Compiler XATMI Library

tpadvertise() Advertises a service name tpunadvertise() Unadvertises a service name

See the Open Distributed Transaction Processing XATMI Application Program Interface Programming Guide for more information about the C Compiler XATMI library.

2.7.2. COBOL Compiler and ASCII COBOL Compiler XATMI

Libraries

The following table lists the communications routines in the COBOL Compiler and ASCII COBOL Compiler XATMI libraries.

Table 2–6. Communications Routines in the COBOL Compiler XATMI Libraries

Routine Description

TPACALL Sends an asynchronous service request TPCALL Sends a service request and waits for the reply TPCANCEL Cancels a call descriptor

TPCONNECT Establishes a conversational service connection TPDISCON Aborts a conversational service connection

TPGETRPLY Receives a reply to an asynchronous service request TPRECV Receives a conversational message

TPRETURN Returns from a service routine and sends the reply TPSEND Sends a conversational message

(33)

The following table lists the service initialization routine in the COBOL Compiler and ASCII COBOL Compiler XATMI libraries.

Table 2–7. Service Initialization Routine in the COBOL Compiler XATMI Libraries

TPSVCSTART Starts a COBOL service and moves service parameters to working storage

The following table lists the service advertisement routines in the COBOL Compiler and ASCII COBOL Compiler XATMI libraries.

Table 2–8. Service Advertisement Routines in the COBOL Compiler XATMI Libraries

TPADVERTISE Advertises a service name TPUNADVERTISE Unadvertises a service name

See the Open Distributed Transaction Processing XATMI Application Program Interface Programming Guide for more information about the COBOL Compiler and ASCII COBOL Compiler XATMI libraries.

2.7.3. JVM on OS 2200 XATMI Library

The following table lists the communications functions in the JVM on OS 2200 XATMI library.

Table 2–9. Communications Functions in the JVM on OS 2200 XATMI Library

acall() Sends an asynchronous service request call() Sends a service request and waits for the reply cancel() Cancels a call descriptor

connect() Establishes a conversational service connection disconnect() Aborts a conversational service connection

getReply() Receives a reply to an asynchronous service request getTpurcode() Accesses the tpurcode variable

(34)

Table 2–9. Communications Functions in the JVM on OS 2200 XATMI Library

returnResults() Returns from a service routine and sends the reply send() Sends a conversational message

The following table lists the buffer management functions in the JVM on OS 2200 XATMI library.

Table 2–10. Buffer Management Functions in the JVM on OS 2200 XATMI Library

allocate() Allocates a typed buffer of a specified type and subtype free() Releases a typed buffer

reallocate() Changes the size of a typed buffer

types() Determines the type, subtype, and size of the buffer when called by an application program that receives a typed buffer

See the Open Distributed Transaction Processing XATMI Application Program Interface Programming Guide for more information about the JVM on OS 2200 XATMI library.

2.7.4. TX Libraries

The following table lists the functions in the C Compiler TX library.

Table 2–11. C Compiler TX Library Functions

tx_begin() Starts a global transaction explicitly

tx_close() Closes the application program’s resource managers tx_commit() Commits the work done by a global transaction and ends the

transaction

tx_info() Obtains current transaction information

tx_open() Opens the application program’s resource managers tx_rollback() Rolls back (aborts) the work done by a global transaction and

ends the transaction

(35)

Table 2–11. C Compiler TX Library Functions

tx_set_transaction_control() Selects chaining mode tx_set_transaction_timeout() Sets transaction timeout value

The following table lists the routines in the COBOL Compiler and ASCII COBOL Compiler TX libraries.

Table 2–12. COBOL Compiler TX Library Routines

TXBEGIN Begins a global transaction

TXCLOSE Closes the application program’s resource managers TXCOMMIT Commits a global transaction

TXINFO Obtains current transaction information

TXOPEN Opens the application program’s resource managers TXROLLBACK Rolls back a global transaction

TXSETCOMMITRET* Sets return point of commit TXSETTIMEOUT Sets transaction timeout value TXSETTRANCTL Selects chaining mode * Not currently supported

The following table lists the functions in the JVM on OS 2200 TX library.

Table 2–13. JVM on OS 2200 TX Library Functions

begin() Starts a global transaction explicitly

close() Closes the application program’s resource managers commit() Commits the work done by a global transaction and

ends the transaction

getInformation() Obtains current transaction information

open() Opens the application program’s resource managers rollback() Rolls back (aborts) the work done by a global

transaction and ends the transaction setCommitReturn() Sets the commit return characteristic

(36)

Table 2–13. JVM on OS 2200 TX Library Functions

setTransactionControl() Sets the transaction control characteristic setTransactionTimeout() Sets transaction timeout value

See the Open Distributed Transaction Processing TX Application Program Interface Programming Guide for more information about the C Compiler, COBOL Compiler, ASCII COBOL Compiler, and JVM on OS 2200 TX libraries.

2.7.5. Diagnostic Services Libraries

The following table lists the functions in the C Compiler diagnostic services library.

Table 2–14. C Compiler Diagnostic Services Library Functions

elog() Writes entries to user-defined event logs for user-defined event types

getdiag() Obtains information useful for error handling

userlog() Writes entries to user-defined event logs for the OLTP_USER event type

The following table lists the routines in the COBOL Compiler and ASCII COBOL Compiler diagnostic services libraries.

Table 2–15. COBOL Compiler Diagnostic Service Library Routines

ELOG_ Writes entries to user-defined event logs for user-defined event types

GETDIAG_ Obtains information useful for error handling

USERLOG_ Writes entries to user-defined event logs for the OLTP_USER event type

See the Open Distributed Transaction Processing Programming Guide for more information about C Compiler, COBOL Compiler, and ASCII COBOL Compiler diagnostic libraries.

Note: Diagnostic service library functions are currently not supported for Virtual

Machine for Java Platform on ClearPath OS 2200.

(37)

When an application program sends data to another application program, it must put the data in a buffer (record). To use the data properly, the receiving applications need to know how the data is structured. Open Distributed Transaction Processing uses Open Group typed buffers and user-defined buffer subtypes to define data structures. These structures ensure that application programs can successfully exchange data, even when they reside on different types of machines.

A buffer subtype specifies exactly how the data in a buffer is structured. You define this structure according to the needs of your application program and the database information it uses. A properly formatted buffer subtype definition is called a VIEW. You use Open Distributed Transaction Processing VIEW utilities to define and install buffer subtypes.

This section describes how to

• Determine which typed buffer to use, X_COMMON or X_C_TYPE

• Define each of the needed buffer subtypes as a VIEW element

• Optionally, use the BUFMAKE utility to translate existing program variables into VIEW descriptions

• Use the VADD utility to install the VIEWs in the Open Distributed Transaction Processing type directory

• Use the VADD or VGET utility to generate a C include element or COBOL COPY element for use by application programs

• Use the VADD utility, or its equivalent, to install the VIEWs on other network machines

When you define and install buffer subtypes, you copy the VIEWs to a repository called the type directory. You specify the name of the type directory file in the

*RESOURCES section of the TMSCONFIG file. (You use a BUFFERS configuration entry to specify BDT_FILE.)

You can copy the type directory file to other Open Distributed Transaction Processing installations with OS 2200 commands or utilities. You do not have to repeat the installation of the VIEWs on other systems.

Note:

Because the type directory file contains information unique to your Open Distributed Transaction Processing installation, you should include the type directory file in your system backup routines.

(38)

This section contains the following topics:

Building VIEWs Description of the VIEW data structure for a buffer subtype

3.1 Using VIEW utility

programs Using the VADD, VDEL, VGET, and View2java utilities to install and maintain VIEWs 3.2 Using BUFMAKE to

create a VIEW (optional)

Using the BUFMAKE processor to create a VIEW from existing program data source code declarations of the input and output variables

3.3

3.1. Building VIEWs

A VIEW contains the definition of the data structure for a buffer subtype associated with an Open Group typed buffer (record). Open Distributed Transaction Processing supports three Open Group typed buffers.

Typed Buffer Use

X_OCTET Use this typed buffer for application programs that completely define the structure of the data to be exchanged. The X_OCTET buffer has no buffer subtype.

X_COMMON Use this typed buffer for COBOL application programs. Use also for C or Java application programs that may communicate with COBOL application programs. You must define and install your own buffer subtypes before you can use X_COMMON typed buffers.

X_C_TYPE Use this type for C, COBOL, or Java application programs. You must define and install your own buffer subtypes before you can use X_C_TYPE typed buffers.

To ensure that other application programs can exchange data with your programs, you must also install the appropriate buffer subtypes on the systems where those

application programs reside. Once these buffer subtypes are installed, Open

Distributed Transaction Processing encodes and decodes the buffer data on behalf of the application programs.

3.1.1. Format of a VIEW

A VIEW is a structure definition you create to define the attributes of data items through a typed buffer. A VIEW follows C language rules for data types and names. You can create multiple VIEWs in the same OS 2200 symbolic element.

See the C Compiler Programming Reference Manual Volume 1 (or other general C reference) for information about rules for C data types, structures, and names.

(39)

A VIEW can contain one or more descriptions of VIEW members (data items). The general format of a VIEW is

VIEW view-name member-description [member-description] ... END where: view-name

is the name of the buffer subtype. It must be a valid C language name up to 16 characters long and must be unique among all installed buffer subtypes.

member-description

defines one member of the VIEW structure. You must include at least one member-description in each VIEW. Each member-description must contain the following fields in the order shown:

type The data type of the member. It can be one of the following data types: • int • short • long • char • float • double • string

• carray (octet array)

• chartranslate (T61 array)

cname The name of the structure member used when generating the C include element, COBOL COPY element, or Java source file for the structure. It must be a valid C language name of a maximum of 32 characters.

When you generate a COBOL COPY element, any underscore characters ( - ) in cname are replaced by hyphens ( - ).

fbname Ignored. This field is included for compatibility with Open Distributed Transaction Processing Pathway, HTP/ic, and TUXEDO /WS software systems. This field must contain a placeholder character, such as a hyphen (-).

count The number of occurrences of the member. It must be an integer greater than zero. You can use this field for defining arrays.

(40)

flag Ignored for all member descriptions except type char. This field is included for compatibility with Open Distributed Transaction

Processing Pathway, HTP/ic, and TUXEDO/WS software systems. This field must contain a place holder character, such as a hyphen ( - ). For type char fields, you may specify the T option. This option identifies these fields as being eligible for local language translation. Local language translation occurs when the following criteria are met:

• The T option is specified on a type char field in the VIEW.

• The service name was configured with a translation table name specification.

• The translation table has been defined in the *RESOURCES section.

size The size of the member in bytes. You must specify the size if the type

value is string, carray, or chartranslate; otherwise, use a hyphen (-). null Ignored. This field is included for compatibility with Open Distributed

Transaction Processing Pathway, HTP/ic, and TUXEDO /WS software systems. This field must contain a placeholder character, such as a hyphen (-).

3.1.2. Corresponding COBOL Data Types for X_COMMON and

X_C_TYPE Buffer Types

If you are building a VIEW for an X_COMMON pr X_C_TYPE buffer type for use by COBOL programs, you can specify the following data types.

C Data Type COBOL Compiler (COBOL 85)

ASCII COBOL Compiler (COBOL 74)

short PIC S9(4) COMP-5 PIC S9(4) COMP

long PIC S9(9) COMP-5 PIC S9(9) COMP

Int PIC S9(9) COMP-5 PIC S9(9) COMP

float COMP-1 COMP-1

double COMP-2 COMP-2

char PIC X(1) PIC X(1)

string PIC X(n) PIC X(n)

carray PIC X(n) PIC X(n)

(41)

Notes:

• The COMP-5 usage specification is available for COBOL Compiler programs only.

• The data types int, float, double, string, and carray cannot be used for X_COMMON buffer subtypes.

• The type (X_C_TYPE or X_COMMON) is associated with the subtype (VIEW) when the application program executes. The type is not stored with the subtype in the type directory.

3.1.3. Comments in a VIEW File

Use the # character for comment lines within the VIEW definition. All characters from the # character to the end of the line are ignored.

3.1.4. Example of a VIEW File

The following example shows a VIEW format for a buffer subtype called employee. As shown, you can insert spaces, new lines, and comments to make the VIEW easy to read.

Comments are delimited by the # character. All characters from the # character to the end of the line are ignored. Comments can also be delimited in the same manner using the $ character.

VIEW employee

# type cname fbname count flag size null # --- --- --- --- ---- ---- ---- char last_name - 30 T - - char first_name - 30 T - - char mi - 1 - - - int emp_no - 1 - - - string ssno - 1 - 12 - string anniv_date - 1 - 9 - short plant - 1 - - - float pay - 2 - - - END

(42)

3.2. Using VIEW Utility Programs

Three VIEW utility programs help system administrators and applications

programmers work with VIEWs. This subsection describes how to use the VADD, VDEL, and VGET utilities.

This subsection contains the following topics.

Using the VADD utility Installing or updating a VIEW; generating C include elements or COBOL COPY elements

3.2.1

Using the VDEL utility Deleting an installed VIEW 3.2.2 Using the VGET utility Obtaining information about installed

VIEWs; generating C include elements or COBOL COPY elements

3.2.3

Using the View2java

compiler Converting a VIEW to a Java source file 3.2.4

3.2.1. Using the VADD Utility

Use the VADD utility to

• Install VIEWs you have defined

• Update the definitions of buffer subtypes already installed

• Generate C include elements and COBOL COPY elements from an installed VIEW Before you are ready to install the VIEW using the VADD utility, you must create a VIEW description of the buffer subtype. For information about choosing a buffer type and creating a VIEW, see 3.1.

After You Install a VIEW

Once the VIEW is installed, you or an applications programmer must do the following before application programs can use the new buffer subtype for network data communications:

1. Update the source code of existing application programs (or create new application programs) to handle the new buffer subtype data structure. For additional information, see the Open Distributed Transaction Processing Programming Guide.

(43)

Note:

Fields in VIEW buffers may be padded to half-word and word boundaries when they are stored by VADD, increasing the length of the buffers. The length stored by VADD should be used when specifying the length of a buffer subtype in an application program. The stored length of the buffer can be found by:

− Inspecting the C include element created by VADD or VGET

− Inspecting the COBOL COPY element created by VADD or VGET

2. Install the new buffer subtypes on other systems, by using the R option with VGET and specifying the VIEW name. Use the VADD utility (or an equivalent utility on other systems).

3. Update the local configuration files with the name of the new buffer subtype. For an Open Distributed Transaction Processing installation, use a BUFFERS configuration entry in the *RESOURCES section of the TMSCONFIG file. For additional information, see the Open Distributed Transaction Processing Administration Guide Volume 1.

VADD Utility Call Format and Options

The call to the VADD utility is as follows:

@OTM$*TM$RUN.VADD[,options] infile[.element] [,outfile] where:

options

is one or more of the following letter options. Option Action

A Generate an ASCII COBOL COPY element containing one PROC for each VIEW. (The A option overrides the C option, if both are included.) C Generate a COBOL COPY element containing one PROC for each

VIEW.

F Generate a Tuxedo viewc compatible COBOL COPY PROC. This option can only be used with either the A or C option. If this option is used, the char entries for a COBOL COPY PROC follow the format used by the Tuxedo viewc compiler. See “Example Use of VADD with F Option,” in Section 3.2.1, for an example of how to use the F option with VADD.

H Generate a C include element containing one structure for each VIEW. I Install a new buffer subtype definition.

(44)

N Suppress standard output. This option prints error information, but does not echo source input statements. If this option is omitted, VADD numbers and echoes all source input statements read from the

infile.element to the standard output stream (PRINT$).

U Update an existing buffer subtype definition (VIEW). If the VIEW does not exist, it is installed.

infile[.element]

specifies the OS 2200 file or element name (version optional) of the input file or symbolic element that contains one or more VIEWs. The infile[.element] parameter is required.

outfile

specifies the OS 2200 program file that receives the output from the A, C, and H options:

• The C include element is written to outfile.element/H.

• The COBOL COPY element is written to outfile.element/COBP.

where element is the VIEW name, truncated to 12 characters if necessary. Underscore ( _ ) characters in the VIEW name, if any, are translated to hyphen ( - ) characters.

If you do not specify outfile, the VADD utility writes the output to the standard output stream (PRINT$).

Example VADD Call

The following example shows a VADD call that

• Installs the example VIEW input file

• Creates C include elements for myview1, myview2, and myview3

• Creates COBOL COPY elements for myview1, myview2, and myview3 @OTM$*TM$RUN.VADD,CHI my*infile.myviews,my*outfile.

Example 3–2. VADD Call

Processing a VIEW

If the VADD utility encounters an error in processing a VIEW, it skips to the next VIEW and continues processing. Correctly coded VIEWs are installed; incorrect VIEWs are not.

If the VADD utility determines that a VIEW with the same name was already installed for the buffer type, it prints a warning message. The VADD utility does not reinstall a duplicate VIEW unless you have specified the U option to update a buffer subtype definition.

(45)

Example of a VIEW Input File

The following example shows an outline of a VIEW input file (infile.element) named my*infile.myviews. It contains the VIEWs myview1, myview2, and myview3.

VIEW myview1 long a ... ... END VIEW myview2 short b ... ... END VIEW myview3 char c ... ... END

Example 3–3. View Input File

Example C Include Elements

The H option specified on the VADD call in the previous example creates the following C include elements:

• MY*OUTFILE.MYVIEW1/H

These elements contain the three C structures shown in the following example. struct myview1 { long a; ... }; struct myview2 { short b; ... }; struct myview3 { char c; ... };

(46)

Example COBOL COPY Elements

The C option specified on the VADD call in the previous example creates the following COBOL COPY elements:

• MY*OUTFILE.MYVIEW1/COBP

These elements contain the three COBOL PROCs shown in the following example. myview1 PROC 05 a PIC S9(9) COMP-5. ... END myview2 PROC 05 b PIC S9(4) COMP-5. ... END myview3 PROC 05 c PIC X. ... END

Example 3–5. COBOL COPY Elements

Illustration of the VADD Utility

The following illustration shows input to the VADD utility that produces

• An installed subtype definition in the type directory

• A C include element

(47)

Figure 3–1. Using the VADD Utility

Note:

For a COBOL COPY element produced by the VADD utility, you may receive a warning message when you process the element with the Procedure Definition Processor (@PDP). The warning message indicates the element is of the wrong type; however, PDP successfully processes the COPY element, and you can ignore the warning.

Example Use of VADD with F Option

Suppose the user defined the following view: VIEW common_d

#type name fbname count flag size null #--- ... ... ... ... ... ... ... char c_array - 10 - - - ... ... ... ... ... ... ... END

If the user specified A or C options when using VADD or VGET, the following COBOL PROC would be created:

Common-d PROC / * * HEADER INFORMATION * ... ... O5 c-array PIC X(10). ... ... * END V IE W v i e w n a m e E N D VA DD U tility T y p e Di re c tory C In c lu d e E le me n t C O B O L C O P Y E l e m e n t