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

unisys Distributed Processing Middleware Open Distributed Transaction Processing Administration Guide Volume 2: Building Applications ClearPath OS 2200 Release 13.1 February 2012 7833 5080 009

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. 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.

Contents 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 7833 5080 009 iii

Contents 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 iv 7833 5080 009

Contents 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 7833 5080 009 v

Contents 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 Transaction Processing Level 4R1... A 3 vi 7833 5080 009

Contents A.3.4. A.3.5. Compatibility with Open Distributed Transaction Processing Level 8R1... A 3 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 7833 5080 009 vii

Contents viii 7833 5080 009

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 7833 5080 009 ix

Figures x 7833 5080 009

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 7833 5080 009 xi

Tables 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 xii 7833 5080 009

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 7833 5080 009 xiii

Examples 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 xiv 7833 5080 009

Section 1 Getting Started 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. Modifying the execution of the server main program. 7833 5080 009 1 1

Getting Started 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 Variable names Function names in text Examples Variable names are intended to be replaced by actual names. They appear as follows: error-file-name The when-return value 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() 1 2 7833 5080 009

Getting Started Item Symbolic constants (keywords, error codes, and flags) Syntax Examples 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 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 ( ) Brackets [ ] Braces { } Vertical bar An ellipsis in examples indicates code that is omitted because it is not pertinent to the discussion. Items in brackets indicate optional entries that you can use or omit. They appear as follows: [APNAME apname] Items in braces indicate choices from which you must include one. They appear as follows: {EXTENDED BASIC} 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. 7833 5080 009 1 3

Getting Started 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 This appendix lists select contents of the Java package com.unisys.os2200.tmapi. 1 4 7833 5080 009

Section 2 Open Distributed Transaction 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 MCP operating environment of ClearPath NX 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. 7833 5080 009 2 1

Open Distributed Transaction Processing Application Development 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 Client programs Client program characteristics and use 2.4 Communications buffer management Transaction boundaries API and diagnostic services libraries Open Distributed Transaction Processing buffers; typed buffers; supported buffer types Transaction Demarcation (TX) calls; transaction mode (AUTOTRAN) configuration Open Group Application to Transaction Manager (XATMI) and TX library application program interfaces (API); diagnostic services libraries 2.3 2.5 2.6 2.7 2 2 7833 5080 009

Open Distributed Transaction Processing Application Development 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. Se rv i ce Ro u ti n e A Cli e nt P ro g ram Request Response Server P ro g ram Se rv i ce Ro u ti n e B Se rv i ce Ro u ti n e C Figure 2 1. Client Calling a Server 7833 5080 009 2 3

Open Distributed Transaction Processing Application Development 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. 2 4 7833 5080 009

Open Distributed Transaction Processing Application Development 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. tpsvrinit service_routine n main service_routine2 service_routine1 service_a service_b tpsvrdone Predefined server module 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. Server tpsvrinit main Service Routines service_routinen service_routine2 service_routine1 tpsvrdone Predefined server module Figure 2 3. Structure of a Java Server 7833 5080 009 2 5

Open Distributed Transaction Processing Application Development 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. For additional information about the MAS utility, see Section 5. 2 6 7833 5080 009

Open Distributed Transaction Processing Application Development 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 Volume 1 Open Distributed Transaction Processing Programming Guide 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. 7833 5080 009 2 7

Open Distributed Transaction Processing Application Development Table 2 1. Server Programming Options Execution Mode High-Volume Transaction Processing (HVTIP) Transaction Processing (TIP) Batch C Compiler Extended Mode Programming COBOL Compiler C Compiler COBOL Compiler C Compiler COBOL Compiler Virtual Machine for the Java Platform onclearpath OS 2200 Basic Mode Programming ASCII COBOL Compiler ASCII COBOL Compiler 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. 2 8 7833 5080 009

Open Distributed Transaction Processing Application Development 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 operating environment of ClearPath NX servers 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 Programming Guide 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. A table in 2.7.1 contains information about XATMI calls that handle typed buffers. 7833 5080 009 2 9

Open Distributed Transaction Processing Application Development 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 X_OCTET X_COMMON X_C_TYPE Function 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. 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. 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. See Section 3 for information about installing buffer subtypes. 2 10 7833 5080 009

Open Distributed Transaction Processing Application Development 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. 7833 5080 009 2 11

Open Distributed Transaction Processing Application Development 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. Topic Description Reference C Compiler XATMI library COBOL Compiler and ASCII COBOL Compiler XATMI libraries JVM on OS 2200 XATMI library TX libraries Diagnostic services libraries Communications functions; buffer management functions; service advertisement functions Communications routines; service initialization routines; service advertisement routines Communications functions; buffer management functions C Compiler, COBOL Compiler, ASCII COBOL Compiler, and JVM on OS 2200 routines C Compiler, COBOL Compiler, and ASCII COBOL Compiler diagnostic services routines 2.7.1 2.7.2 2.7.3 2.7.4 2.7.5 2 12 7833 5080 009

Open Distributed Transaction Processing Application Development 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 tpacall() tpcall() tpcancel() tpconnect() tpdiscon() tpgetrply() tprecv() tpreturn() tpsend() Description Sends an asynchronous service request Sends a service request and waits for the reply Cancels a call descriptor Establishes a conversational service connection Aborts a conversational service connection Receives a reply to an asynchronous service request Receives a conversational message Returns from a service routine and sends the reply 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 Function tpalloc() tpfree() tprealloc() tptypes() Description Allocates a typed buffer of a specified type and subtype Releases a typed buffer Changes the size of a typed buffer Determines the type, subtype, and size of the buffer when called by an application program that receives a typed buffer 7833 5080 009 2 13

Open Distributed Transaction Processing Application Development 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 Function Description tpadvertise() tpunadvertise() Advertises a service name 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 TPACALL TPCALL TPCANCEL TPCONNECT TPDISCON TPGETRPLY TPRECV TPRETURN TPSEND Description Sends an asynchronous service request Sends a service request and waits for the reply Cancels a call descriptor Establishes a conversational service connection Aborts a conversational service connection Receives a reply to an asynchronous service request Receives a conversational message Returns from a service routine and sends the reply Sends a conversational message 2 14 7833 5080 009

Open Distributed Transaction Processing Application Development 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 Routine TPSVCSTART Description 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 Routine Description TPADVERTISE TPUNADVERTISE Advertises a service name 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 Function acall() call() cancel() connect() disconnect() getreply() gettpurcode() receive() Description Sends an asynchronous service request Sends a service request and waits for the reply Cancels a call descriptor Establishes a conversational service connection Aborts a conversational service connection Receives a reply to an asynchronous service request Accesses the tpurcode variable Receives a conversational message 7833 5080 009 2 15

Open Distributed Transaction Processing Application Development Table 2 9. Communications Functions in the JVM on OS 2200 XATMI Library Function returnresults() send() Description Returns from a service routine and sends the reply 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 Function allocate() free() reallocate() types() Description Allocates a typed buffer of a specified type and subtype Releases a typed buffer Changes the size of a typed buffer 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 Function tx_begin() tx_close() tx_commit() tx_info() tx_open() tx_rollback() tx_set_commit_return() Description Starts a global transaction explicitly Closes the application program s resource managers Commits the work done by a global transaction and ends the transaction Obtains current transaction information Opens the application program s resource managers Rolls back (aborts) the work done by a global transaction and ends the transaction Sets return point of commitment 2 16 7833 5080 009

Open Distributed Transaction Processing Application Development Table 2 11. C Compiler TX Library Functions Function tx_set_transaction_control() tx_set_transaction_timeout() Selects chaining mode Sets transaction timeout value Description The following table lists the routines in the COBOL Compiler and ASCII COBOL Compiler TX libraries. Table 2 12. COBOL Compiler TX Library Routines Routine Description TXBEGIN TXCLOSE TXCOMMIT TXINFO TXOPEN TXROLLBACK TXSETCOMMITRET* TXSETTIMEOUT TXSETTRANCTL * Not currently supported Begins a global transaction Closes the application program s resource managers Commits a global transaction Obtains current transaction information Opens the application program s resource managers Rolls back a global transaction Sets return point of commit Sets transaction timeout value Selects chaining mode The following table lists the functions in the JVM on OS 2200 TX library. Table 2 13. JVM on OS 2200 TX Library Functions Function Description begin() close() commit() getinformation() open() rollback() setcommitreturn() Starts a global transaction explicitly Closes the application program s resource managers Commits the work done by a global transaction and ends the transaction Obtains current transaction information Opens the application program s resource managers Rolls back (aborts) the work done by a global transaction and ends the transaction Sets the commit return characteristic 7833 5080 009 2 17

Open Distributed Transaction Processing Application Development Table 2 13. JVM on OS 2200 TX Library Functions settransactioncontrol() settransactiontimeout() Sets the transaction control characteristic 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 Function elog() getdiag() userlog() Description Writes entries to user-defined event logs for user-defined event types Obtains information useful for error handling 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 Routine ELOG_ GETDIAG_ USERLOG_ Description Writes entries to user-defined event logs for user-defined event types Obtains information useful for error handling 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. 2 18 7833 5080 009

Section 3 Buffer Subtypes 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. 7833 5080 009 3 1

Buffer Subtypes This section contains the following topics: Topic Description Reference Building VIEWs Using VIEW utility programs Using BUFMAKE to create a VIEW (optional) Description of the VIEW data structure for a buffer subtype Using the VADD, VDEL, VGET, and View2java utilities to install and maintain VIEWs Using the BUFMAKE processor to create a VIEW from existing program data source code declarations of the input and output variables 3.1 3.2 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 X_OCTET X_COMMON X_C_TYPE Use 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. 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. 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. 3 2 7833 5080 009

Buffer Subtypes 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 fbname count 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 ( - ). 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 ( - ). The number of occurrences of the member. It must be an integer greater than zero. You can use this field for defining arrays. 7833 5080 009 3 3

Buffer Subtypes 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 null 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 ( - ). 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) chartranslate PIC X(n) PIC X(n) 3 4 7833 5080 009

Buffer Subtypes 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 Example 3 1. Example VIEW File 7833 5080 009 3 5

Buffer Subtypes 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. Topic Description Reference 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. 3 6 7833 5080 009

Buffer Subtypes 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 A C F H I Action Generate an ASCII COBOL COPY element containing one PROC for each VIEW. (The A option overrides the C option, if both are included.) Generate a COBOL COPY element containing one PROC for each VIEW. 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. Generate a C include element containing one structure for each VIEW. Install a new buffer subtype definition. 7833 5080 009 3 7

Buffer Subtypes N U 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$). 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: Example VADD Call 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$). 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 Processing a VIEW @OTM$*TM$RUN.VADD,CHI my*infile.myviews,my*outfile. Example 3 2. VADD Call 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. 3 8 7833 5080 009

Buffer Subtypes 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 C Include Elements Example 3 3. View Input File The H option specified on the VADD call in the previous example creates the following C include elements: MY*OUTFILE.MYVIEW1/H MY*OUTFILE.MYVIEW2/H MY*OUTFILE.MYVIEW3/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;... }; Example 3 4. C Include Element 7833 5080 009 3 9

Buffer Subtypes 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 MY*OUTFILE.MYVIEW2/COBP MY*OUTFILE.MYVIEW3/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 Illustration of the VADD Utility Example 3 5. COBOL COPY Elements The following illustration shows input to the VADD utility that produces An installed subtype definition in the type directory A C include element A COBOL COPY element 3 10 7833 5080 009

Buffer Subtypes V IE W v i ew n am e E N D VA DD Utility T y p e Di rectory C Include E le me nt C O B O L C O P Y E l em e nt 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 7833 5080 009 3 11

Buffer Subtypes The user can now (optionally) specify an F option, along with either the A or C options, to produce the following COBOL PROC: Common-d PROC / * * HEADER INFORMATION *...... O5 c-array PIC X(1). OCCURS 10 TIMES....... * END 3.2.2. Using the VDEL Utility Use the VDEL utility to delete a VIEW installed with the VADD utility. If the VIEW is no longer used, be sure to delete the VIEW from all machines in the network on which the VIEW is installed. VDEL Utility Call Format and Options The call to the VDEL utility is as follows: @OTM$*TM$RUN.VDEL [infile] where infile specifies the name of the data file or symbolic element that contains one or more VIEW names previously added using the VADD utility. If infile is a symbolic element in a program file, the element and version name must be specified. If infile is not specified, the VDEL utility reads the type entries from the standard input stream (READ$). Example VDEL Call The following example shows the call used to delete the VIEWs named in the runstream. @OTM$*TM$RUN.VDEL myview1 myview2 @EOF Example 3 6. VDEL Call 3 12 7833 5080 009

Buffer Subtypes 3.2.3. Using the VGET Utility Use the VGET utility to do one or more of the following: Generate a COBOL COPY element for each VIEW Generate a C include element for each VIEW Produce a report on specific buffers or all installed buffers Write VIEWs to a program or an SDF file VGET Utility Call Format and Options The call to the VGET utility is as follows: @OTM$*TM$RUN.VGET[,options] [infile][,outfile] where: options is one or more of the following letter options: Option A C F H N R Action Generate an ASCII COBOL Compiler COPY element of PROCs, one for each VIEW name entry. (The A option overrides the C option, if both are included.) Generate a COBOL Compiler COPY element of PROCs, one for each VIEW name entry. 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. The VADD utility uses an equivalent F option. 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. Generate a C include element of structure declarations, one for each VIEW name entry. Suppress standard output. This option prints error information, but does not echo source input statements. If this option is omitted, VGET numbers and echoes all source input statements read from the infile.element to the standard output stream (PRINT$). Produce a report about specific buffers or all installed buffers. If no buffers are specified, reports for all installed buffers are produced. If you specify the R option, you cannot specify options A, C, H, or V. 7833 5080 009 3 13

Buffer Subtypes Option S Action Produce a VIEW report that gets written to an SDF file, by using with the V option. V Produce a VIEW for specific subtype definitions or all installed definitions. If no subtypes are specified, VIEWs for all installed subtypes are produced. The latter method can be used as a means to backup the BDT file from time to time because the VIEWs produced can be input to VADD for reloading. If you specify the V option, you cannot specify options A, C, H, or R. infile specifies the name of the data file or symbolic element that contains one or more VIEW name entries (one per line) of buffer subtypes previously added using the VADD utility. If infile is a symbolic element in a program file, the element and version name must be specified. If infile is not specified, the VGET utility reads the type entries from the standard input stream (READ$). outfile specifies the name of the file that receives the VGET output. This file is a program file for all options except when using the S option whereby the output file is an SDF file. For C include elements and COBOL COPY elements, the name of the output element is taken from the name of each VIEW name processed. Each element name is truncated to 12 characters if necessary. Underscore ( _ ) characters in VIEW names, if any, are translated to hyphen ( - ) characters. The output is written to any of the following, depending on the value of options: C include elements are written to outfile.element/h. COBOL COPY elements are written to outfile.element/cobp. Reports are written to outfile.report. VIEWs are written to outfile.view or outfile if the S option is specified. If outfile is not specified, the VGET utility writes the output to the standard output stream (PRINT$). Illustration of the VGET Utility The following illustration shows input to the VGET utility that produces A C include element A COBOL COPY element A report about installed buffer subtypes Output of installed VIEWs 3 14 7833 5080 009

Buffer Subtypes V IE W v i ew n am e E N D VGET Utility VIE W R e port C Include E le me nt C O B O L C O P Y E l em e nt Figure 3 2. Using the VGET Utility Note: For a COBOL COPY element produced by the VGET utility, you may receive a warning message when you process the element with the Procedure Definition Processor (@PDP). The warning message indicates that the element is of the wrong type; however, PDP successfully processes the COPY element, and you can ignore the warning. Example VGET Call The following example shows a VGET call that uses all options and writes the output to elements in a program file. @OTM$*TM$RUN.VGET,CH,my*outfile. myview1 myview2 @EOF Example 3 7. VGET Call 3.2.4. Using the View2java Compiler The View2java tool converts Open Distributed Transaction Processing VIEW files to Java source files. It parses the Open Distributed Transaction Processing VIEW files and creates Java source files that implement the TransactionView interface in the com.unisys.os2200.tmapi package. Constructors are created along with methods to set and get each variable defined in the Open Distributed Transaction Processing VIEW file. Constructors initialize fields as specified in the VIEW file. Each variable in the VIEW file has set and get methods with the appropriate signature and return type. The methods use the TransactionTP.Buffer class to access the data items. For more information on the TransactionView interface and TransactionTP.Buffer class definitions, see Appendix C. 7833 5080 009 3 15

Buffer Subtypes View2java Call Format and Options The call to the View2java compiler from Windows is as follows: java View2java [opts] [<view file> [<view file>...]] where opts is one or more of the following: Option Action -b Generate byte accessor methods for char and carray variables in aview. -h Display a usage message. All other arguments are ignored. -i Display VIEW file listing(s). -o Display Java class file listing(s). -8 Generate Java class file for 8-byte longs. <view file>is the source file for the VIEW(s). This is required for all options except-h. Example of the View2java Compiler The following example shows Open Distributed Transaction Processing VIEW File and the Java source file generated with the View2java tool. Open Distributed Transaction Processing VIEW File VIEW ctype_d # type name fbname count flag size null #--------------------------------------------------------- short machinekey - 1 - - - short test - 1 - - - int i - 1 - - - short s - 1 - - - long l - 1 - - - float f - 1 - - - double d - 1 - - - char c - 1 - - - string string - 1-128 - 3 16 7833 5080 009

Buffer Subtypes carray data - 1-128 - int i_array - 10 - - - short s_array - 10 - - - long l_array - 10 - - - float f_array - 10 - - - double d_array - 10 - - - char c_array - 10 - - - string string_array - 10-128 - carray data_array - 10-128 - short zero_test - 1 - - - END Java Source Code // Generated by the OpenDTP View2java compiler on // Tue Jan 25 15:52:48 CST 2005 import com.unisys.os2200.tmapi.*; public class Ctype_d implements TransactionView { private TransactionTP.Buffer buffer; private String type; private String subtype; public TransactionTP.Buffer getbuffer() { return(buffer); } public String gettype() { return(type); } public String getsubtype() { 7833 5080 009 3 17

Buffer Subtypes return(subtype); } protected void finalize() throws Throwable { super.finalize(); TransactionTP.free(buffer); } public void setmachinekey(short machinekey) { buffer.setshort(0, machinekey); } public short getmachinekey() { return(buffer.getshort(0)); } public void settest(short test) { buffer.setshort(2, test); } public short gettest() { return(buffer.getshort(2)); } public void seti(int i) { buffer.setint(4, i); } public int geti() 3 18 7833 5080 009

Buffer Subtypes { return(buffer.getint(4)); } public void sets(short s) { buffer.setshort(8, s); } public short gets() { return(buffer.getshort(8)); } public void setl(long l) { buffer.setlong(10, l); } public long getl() { return(buffer.getlong(10)); } public void setf(float f) { buffer.setfloat(14, f); } public float getf() { return(buffer.getfloat(14)); } public void setd(double d) 7833 5080 009 3 19

Buffer Subtypes { buffer.setdouble(18, d); } public double getd() { return(buffer.getdouble(18)); } public void setc(char c) { buffer.setchar(26, c); } public char getc() { return(buffer.getchar(26)); } public void setstring(string string) { buffer.setstring(27, string, 128); } public String getstring() { return(buffer.getstring(27, 128)); } public void setdata(char data[]) { buffer.setchar(155, data); } public char[] getdata() 3 20 7833 5080 009

Buffer Subtypes { return(buffer.getchar(155, 128)); } public void setdataat(char data, int row) { buffer.setchar(155 + (1 * row), data); } public char getdataat(int row) { return(buffer.getchar(155 + (1 * row))); } public void seti_array(int i_array[]) { buffer.setint(283, i_array); } public int[] geti_array() { return(buffer.getint(283, 10)); } public void seti_arrayat(int i_array, int row) { buffer.setint(283 + (4 * row), i_array); } public int geti_arrayat(int row) { return(buffer.getint(283 + (4 * row))); } public void sets_array(short s_array[]) { 7833 5080 009 3 21

Buffer Subtypes buffer.setshort(323, s_array); } public short[] gets_array() { return(buffer.getshort(323, 10)); } public void sets_arrayat(short s_array, int row) { buffer.setshort(323 + (2 * row), s_array); } public short gets_arrayat(int row) { return(buffer.getshort(323 + (2 * row))); } public void setl_array(long l_array[]) { buffer.setlong(343, l_array); } public long[] getl_array() { return(buffer.getlong(343, 10)); } public void setl_arrayat(long l_array, int row) { buffer.setlong(343 + (4 * row), l_array); } public long getl_arrayat(int row) { 3 22 7833 5080 009

Buffer Subtypes return(buffer.getlong(343 + (4 * row))); } public void setf_array(float f_array[]) { buffer.setfloat(383, f_array); } public float[] getf_array() { return(buffer.getfloat(383, 10)); } public void setf_arrayat(float f_array, int row) { buffer.setfloat(383 + (4 * row), f_array); } public float getf_arrayat(int row) { return(buffer.getfloat(383 + (4 * row))); } public void setd_array(double d_array[]) { buffer.setdouble(423, d_array); } public double[] getd_array() { return(buffer.getdouble(423, 10)); } public void setd_arrayat(double d_array, int row) { 7833 5080 009 3 23

Buffer Subtypes buffer.setdouble(423 + (8 * row), d_array); } public double getd_arrayat(int row) { return(buffer.getdouble(423 + (8 * row))); } public void setc_array(char c_array[]) { buffer.setchar(503, c_array); } public char[] getc_array() { return(buffer.getchar(503, 10)); } public void setc_arrayat(char c_array, int row) { buffer.setchar(503 + (1 * row), c_array); } public char getc_arrayat(int row) { return(buffer.getchar(503 + (1 * row))); } public void setstring_array(string string_array[]) { buffer.setstring(513, string_array, 128); } public String[] getstring_array() { 3 24 7833 5080 009

Buffer Subtypes return(buffer.getstring(513, 128, 10)); } public void setstring_arrayat(string string_array, int row) { buffer.setstring(513 + (128 * row), string_array, 128); } public String getstring_arrayat(int row) { return(buffer.getstring(513 + (128 * row), 128)); } public void setdata_array(char data_array[][]) { buffer.setchar(1793, data_array, 128); } public char[][] getdata_array() { return(buffer.getchar(1793, 128, 10)); } public void setdata_arrayat(char data_array[], int row) { buffer.setchar(1793 + (128 * row), data_array); } public char[] getdata_arrayat(int row) { return(buffer.getchar(1793 + (128 * row), 128)); } public void setzero_test(short zero_test) { buffer.setshort(3073, zero_test); 7833 5080 009 3 25

Buffer Subtypes } public short getzero_test() { return(buffer.getshort(3073)); } public long getlength() { return(3075); } public static long getsize() { return(3075); } public String tostring() { return( "[type=" + type + ",subtype=" + subtype + ",Machinekey=" + getmachinekey() + ",Test=" + gettest() + ",I=" + geti() + ",S=" + gets() + ",L=" + getl() + ",F=" + getf() + ",D=" + getd() + ",C=" + getc() + ",String=" + getstring() + ",Data=" + TransactionTP.toString(getData()) + ",I_array=" + TransactionTP.toString(getI_array()) + ",S_array=" + TransactionTP.toString(getS_array()) + ",L_array=" + TransactionTP.toString(getL_array()) + ",F_array=" + TransactionTP.toString(getF_array()) + 3 26 7833 5080 009

Buffer Subtypes ",D_array=" + TransactionTP.toString(getD_array()) + ",C_array=" + TransactionTP.toString(getC_array()) + ",String_array=" + TransactionTP.toString(getString_array()) + ",Data_array=" + TransactionTP.toString(getData_array()) + ",Zero_test=" + getzero_test() + "]"); } public Ctype_d() throws TPException { this.buffer = TransactionTP.allocate("X_C_TYPE", "ctype_d", 3075); } this.type = "X_C_TYPE"; this.subtype = "ctype_d"; public Ctype_d(TransactionTP.Buffer buffer) { } this.buffer = buffer; this.type = "X_C_TYPE"; this.subtype = "ctype_d"; } Example of the View2java Compiler The following example shows Open Distributed Transaction Processing VIEW File and the Java source file generated with the View2java tool. Open Distributed Transaction Processing VIEW File VIEW ctype_d # type name fbname count flag size null #--------------------------------------------------------- long l - 1 - - - float f - 1 - - - char c - 1 - - - string string - 1-128 - carray data - 1-128 - int i_array - 10 - - - 7833 5080 009 3 27

Buffer Subtypes short s_array - 10 - - - float f_array - 10 - - - char c_array - 10 - - - string string_array - 10-128 - carray data_array - 10-128 - END Java Source Code import com.unisys.os2200.tmapi.*; public class Ctype_d implements TransactionView { private TransactionTP.Buffer buffer; private String type; private String subtype; public TransactionTP.Buffer getbuffer() { return buffer; } public String gettype() { return type; } public String getsubtype() { return subtype; } protected void finalize() throws Throwable { super.finalize(); TransactionTP.free(buffer); } void setl(long l) { buffer.setlong(0, l); } long getl() { return buffer.getlong(0); } void setf(float f) { buffer.setfloat(4, f); } 3 28 7833 5080 009

Buffer Subtypes float getf() { return buffer.getfloat(4); } void setc(char c) { buffer.setchar(8, c); } char getc() { return buffer.getchar(8); } void setstring(string string) { buffer.setstring(9, string, 128); } String getstring() { return buffer.getstring(9, 128); } void setdata(char data[]) { buffer.setchar(137, data); } char[] getdata() { return buffer.getchar(137, 128); } void seti_array(int i_array[]) { buffer.setint(265, i_array); } int[] geti_array() { return buffer.getint(265, 10); } void sets_array(short s_array[]) { buffer.setshort(305, s_array); } short[] gets_array() 7833 5080 009 3 29

Buffer Subtypes { } return buffer.getshort(305, 10); void setf_array(float f_array[]) { buffer.setfloat(325, f_array); } float[] getf_array() { return buffer.getfloat(325, 10); } void setc_array(char c_array[]) { buffer.setchar(365, c_array); } char[] getc_array() { return buffer.getchar(365, 10); } void setstring_array(string string_array[]) { buffer.setstring(375, string_array, 128); } String[] getstring_array() { return buffer.getstring(375, 128, 10); } void setdata_array(char data_array[][]) { buffer.setchar(1655, data_array, 128); } char[][] getdata_array() { return buffer.getchar(1655, 128, 10); } public Ctype_d() throws TPException { this(transactiontp.allocate("x_c_type", "ctype_d", 2935)); this.type = "X_C_TYPE"; this.subtype = "ctype_d"; } 3 30 7833 5080 009

Buffer Subtypes public Ctype_d(TransactionTP.Buffer buffer) { this.buffer = buffer; this.type = "X_C_TYPE"; this.subtype = "ctype_d"; } public long getlength() { return 2935; } public String tostring() { return "[type=" + type + ",subtype=" + subtype + ",L=" + getl() + ",F=" + getf() + ",C=" + getc() + ",String=" + getstring() + ",Data=" + TransactionTP.toString(getData()) + ",I_array=" + TransactionTP.toString(getI_array()) + ",S_array=" + TransactionTP.toString(getS_array()) + ",F_array=" + TransactionTP.toString(getF_array()) + ",C_array=" + TransactionTP.toString(getC_array()) + ",String_array=" + TransactionTP.toString(getString_array()) + ",Data_array=" + TransactionTP.toString(getData_array()) + "]"; } } Example 3 8. Open Distributed Transaction Processing VIEW File and Java Source File 3.3. Using BUFMAKE to Create a VIEW There may be times when you want to rewrite existing programs to create new client and server programs. When you want to do this, the BUFMAKE processor can be used to create a starting point VIEW from existing source code declarations of the input and output variables in your application program. VIEWs do not support all data types used in the source code declarations of the input and output variables. Therefore, when creating a VIEW, BUFMAKE chooses the most appropriate VIEW data type for each variable in the source code declaration. The BUFMAKE processor was originally developed to translate data for the Heritage Application Access (HAA) environment. For more information, see the Heritage Application Access Administration and Programming Guide. 7833 5080 009 3 31

Buffer Subtypes 3.3.1. Using the BUFMAKE Processor You can use BUFMAKE processor to Generate Open Distributed Transaction Processing VIEWs from standard programming language data variables Generate C header files or COBOL COPY files to match the VIEW Optionally generate the Open Distributed Transaction Processing VIEWs compatible with Field Manipulation Language (FML) fielded buffers BUFMAKE Input The BUFMAKE processor takes an OS 2200 file or file element as input. The input file or element contains the data definition for one of your application program's I/O buffers. The source of the buffer's data definition is one of the following: A Display Processing System form definition (DPS Working Storage). One of the structures provided for Display Processing System non-form I/O. A copy of the set of standard programming language variable declarations which define the buffer in your non-dps program. Data Definitions Accepted by BUFMAKE BUFMAKE accepts data declarations for standard programming language variables from C and COBOL programming languages. BUFMAKE defines a standard programming language variable as one of the data types listed for the different languages. These definitions are based on the restrictions specified in the topic BUFMAKE Output, in Section 3.3.1. C Data Variables BUFMAKE defines a standard programming language variable as one of the following data types: #pragma statements (ignored) #define statements (ignored) Single-line and multiline comments (ignored) Blank lines (ignored) typedef structure statements Structures and single-dimensional arrays of structures Unions and single-dimensional arrays of unions Note: Union members must be of equal size. Initial values for structures 3 32 7833 5080 009

Buffer Subtypes Variable types: char double float int long short Note: All C variables must be within a C structure. Variable prefixes: Signed Unsigned Single-dimensional arrays of variables Variables with bit lengths: int COBOL Data Variables BUFMAKE defines a standard programming language variable as one of the following data types: Comment lines (ignored) Blank lines (ignored) PROC statements END statements for PROC VALUE clauses VALUE SPACE clause VALUE SPACES clauses VALUE ZERO clause VALUE ZEROES clause Variable types: COMP COMP-1 COMP-2 PIC 1(n) PIC S1(n) PIC 1(n) BINARY-1 PIC S1(n) BINARY-1 PIC A(n) 7833 5080 009 3 33

Buffer Subtypes PIC X(n) PIC 9(n) PIC S9(n) PIC 9(n) COMP PIC S9(n) COMP PIC 9(n) BINARY PIC S9(n) BINARY Note: All PICTURE clauses must use replication symbols. For example, BUFMAKE accepts PIC X(3) or PIC 9(1), but not PIC XXX or PIC 9. INDEXED BY clauses OCCURS clauses REDEFINES clauses (group level item redefining group level item) BUFMAKE Input Restrictions BUFMAKE is not intended to duplicate the syntax parser for OS 2200 compilers. Instead, BUFMAKE accepts a subset of valid data declaration syntax. BUFMAKE imposes the following restrictions on its input: C COBOL Data must be within a structure or multiple structures. Members of unions must be of equal size. You must use replication symbols in the character string portion of PICTURE clauses. For example, BUFMAKE accepts PIC X(3) and PIC X(1), but not PIC XXX or PIC X. Data definitions cannot contain SYNCH clauses. Data cannot include Fieldata characters. Both data names referenced on REDEFINES clauses must be group level items. Groups must be of equal size and must contain the same number and type of variables. 3 34 7833 5080 009

Buffer Subtypes BUFMAKE Output From the input file or element, the BUFMAKE processor creates A VIEW for the I/O buffer defined by the Display Processing System form definition, Display Processing System non-form I/O data structure, or set of standard programming language variable declarations within the input file You input this VIEW to the VADD processor on the OS 2200 system hosting your service and to the VIEW compiler on the systems hosting the client programs. Either a COBOL COPY file or a C header file You include this COBOL COPY file or C header file in client programs executing on OS 2200 systems. If the BUFMAKE input file contains initial values for the standard programming language variables, those initial values are retained in this COBOL COPY file or C header file. FML Fielded Buffer Compatible VIEWs TUXEDO-based products offer a feature that provides a proprietary self-defining buffer type, FML fielded buffers. BUFMAKE has an optional command parameter, FML_OUTPUT, to indicate FML compatible output is desired. The FML_OUTPUT parameter lets you manipulate your data in FML fielded buffers for TUXEDO-based client programs. By default, BUFMAKE generates VIEWs that are FML-independent. When the FML_OUTPUT parameter is invoked, BUFMAKE generates an FMLcompatible VIEW, its corresponding FML field table, and a COBOL COPY file or C header file. Naming Conventions for BUFMAKE Output The BUFMAKE processor produces OS 2200 program files with elements containing VIEWS, C header files, COBOL COPY files, and optional FML field tables. BUFMAKE uses the OUTFILE parameter as the file base name (See BUFMAKE Commands and Command Parameters, in Section 3.3.4, for more information on BUFMAKE command parameters and values). BUFMAKE names the output elements as follows: Output Type View C header file COBOL COPY file FML field table Naming Convention XXXX/VIEW XXXX/H XXXX/COBP XXXX/FIELD-TABLE where XXXX is the subtype in use. If the subtype name is more than 12 characters, the first 12 characters are used for the element name. Underscore characters in the subtype name are changed to hyphens in the element name. 7833 5080 009 3 35

Buffer Subtypes 3.3.2. VIEW Translation The following table shows the translation of OS 2200 programming language variable types to Open Distributed Transaction Processing working storage VIEW variable types. Table 3 1. Data Type Translation: Server Perspective OS 2200 Programming Language Variable Type in OS 2200 Language Variable Type in Open Distributed Transaction Processing VIEW C char char double float int long int : n short double float long long n = 1 16, short n = 17 36, long long COBOL COMP-1 float COMP-2 PIC 1(n) PIC S1(n) PIC 1(n) BINARY-1 PIC S1(n) BINARY-1 PIC 9(n) PIC S9(n) PIC 9(n) BINARY PIC S9(n) BINARY PIC 9(n) COMP PIC S9(n) COMP PIC A(n) PIC X(n) double n = 1 16, short n = 17 36, long n > 36, ERROR n = 1,2 short n = 3,4,5,6,7,8,9,10 long n=1,2 short n=3,4,5,6,7,8,9,10 long n > 10 ERROR char char 3 36 7833 5080 009

Buffer Subtypes 3.3.3. Header Translation The following table shows the translation of OS 2200 programming language variable types to Open Distributed Transaction Processing working storage VIEW variable types. Table 3 2. Data Type Translation: Client Perspective Client Programming Language Variable Type in Open Distributed Transaction Processing VIEW Variable Type in OS 2200 Language C carray char char double float int long short char double float int long short COBOL-74 char PIC X(n) long short PIC S9(9) CO COBOL-85 char PIC X(n) long short 3.3.4. Starting the BUFMAKE Processor PIC S9(4) COMP PIC S9(9) COMP-5 PIC S9(4) COMP-5 Assuming that TM$RUN is the username on the installed Open Distributed Transaction Processing TM$RUN file (see the Open Distributed Transaction Processing Administration Guide Volume 1), the BUFMAKE command interface is executed as follows: @TM$RUN.BUFMAKE The BUFMAKE processor outputs the following ID line: BUFMAKE xry -- day mmm dd hh:mm:ss yyyy followed by: Enter command 7833 5080 009 3 37

Buffer Subtypes BUFMAKE Commands and Command Parameters Once the command prompt is received, commands may be entered in the following format: command_name [parameter=value] where command_name specifies one of the BUFMAKE commands in Table 3-3. Table 3 3. BUFMAKE Processor Commands and Command Parameters BUFMAKE Command Name Purpose Parameters Accepted DELETE Deletes a stored translation from the Open Distributed Transaction Processing Translation directory, which is used by HAA. You only need to use this command if you have previously set STORE_TRANSLATION to YES. TYPE SUBTYPE EXIT Terminates BUFMAKE execution. None QUERY TRANSLATE Controls the BUFMAKE query mode. When query mode is on, BUFMAKE queries you for input parameters. When query mode is off, BUFMAKE expects addstream input and uses default values for all parameters not specified. If you do not specify the MODE parameter, the current QUERY is displayed. Translates standard programming language data variables and generates an Open Distributed Transaction Processing VIEW and either a C header file or a COBOL COPY file. Optionally, generates the Open Distributed Transaction Processing VIEW compatible with FML fielded buffers and generates a corresponding FML field table. MODE = OFF or MODE = ON TYPE SUBTYPE INFILE OUTFILE INPUT_LANGUAGE OUTPUT_LANGUAGE FML_OUTPUT INTERFACE STORE_TRANSLATION COBOL_REDEFINES C_UNION FORMAT parameter=value provides additional information for some commands. The parameters and allowed values are shown in the following table. 3 38 7833 5080 009

Buffer Subtypes Table 3 4. BUFMAKE Command Parameters and Values Parameter Name and Description Acceptable Values (* = Default) Restrictions C_UNION Identifies which portion of a C union should be used for the translation. COBOL_REDEFINE Identifies which portion of a COBOL redefine should be used for the translation. FML_OUTPUT Indicates FML-based output is desired. By using the FML-based output generated from this parameter, client application programs executing in a TUXEDO-based environment can transfer data between VIEW buffers and FML fielded buffers. When set to YES, BUFMAKE generates an FML-based VIEW and the corresponding field table. When set to NO, BUFMAKE generates an FML-independent VIEW and does not generate an FML field table. FORMAT Identifies the FORMAT of input when the INTERFACE is DPS. INFILE Identifies the file (element and version optional) containing the standard programming language data variables to be used as input for the translation. INPUT_LANGUAGE Identifies the input language for the standard programming language data variables found in INFILE. FIRST * LAST FIRST * LAST YES NO * SCREEN * DPSLINE DPSPRTLINE DPSGETSCREEN DPSPUTSCREEN DPSTEMPLATE DPSTERMINAL DPSMSG Must be a valid OS 2200 file name; may contain element and version. C COBOL Used only if INPUT_LANGUAGE is set to C. Used only if INPUT_LANGUAGE is set to COBOL. None When INFILE is a Display Processing System Working Storage procedure, you must set FORMAT to SCREEN. When INFILE is one of the storage structures provided for Display Processing System nonform I/O, you must set FORMAT to the element name of the working storage structure. For example, when INFILE = TM$UTIL.DPSLINE/H, you must set FORMAT = DPSLINE. Must be a valid OS 2200 file name. Must choose one of the allowed values. 7833 5080 009 3 39

Buffer Subtypes Table 3 4. BUFMAKE Command Parameters and Values Parameter Name and Description Acceptable Values (* = Default) Restrictions INTERFACE Identifies the Access interface implementation that will be used with this translation. OUTFILE Identifies the output file (element and version not allowed) for storing the output from the TRANSLATE command. The VIEW description is stored in outfile. subtype/view, the C header file is stored in outfile. subtype/h, the COBOL COPY file is stored in outfile. subtype/cobp, and the optional FML field table is stored in outfile. subtype/field- TABLE. OUTPUT_LANGUAGE Identifies the output language. STORE_TRANSLATION Indicates that the translation is to be stored. GENERAL * DPS If you use INTERFACE = DPS, you may be prompted for additional commands that are described in the Heritage Application Access Administration and Programming Guide Any valid OS 2200 file name. Standard output stream * C * COBOL-74 COBOL-85 YES * NO None The file name cannot contain an element or version. If the TYPE is set to X_C_TYPE, only C is allowed. If the INTERFACE is set to DPS, only YES is allowed. 3 40 7833 5080 009

Buffer Subtypes Table 3 4. BUFMAKE Command Parameters and Values Parameter Name and Description Acceptable Values (* = Default) Restrictions SUBTYPE Identifies the unique subtype for the Open Distributed Transaction Processing buffer to be created in the translation. TYPE Identifies the type for the Open Distributed Transaction Processing buffer to be created in the translation. Allowed value is any 16-character name containing the characters A..Z, 0..9, and _. X_C_TYPE * X_COMMON The subtype is an arbitrary 16- character user-defined name, except when you specify SCREEN for the FORMAT parameter. When you set the FORMAT parameter to SCREEN, you must set SUBTYPE equal to the Display Processing System form name. It is recommended that you set SUBTYPE equal to the element name of the working storage structure for COBOL and for Display Processing System nonform I/O, For C the struct name is recommended. None BUFMAKE commands and parameters are column-insensitive and case-insensitive, but they may not be abbreviated. Any command may be continued on the next input line by use of the continuation character (;). Upon termination, BUFMAKE produces the following output: End BUFMAKE. x ERRORS y WARNINGS 3.3.5. Example of BUFMAKE Execution The BUFMAKE processor is used to create a VIEW using type X_COMMON and subtype EMPSVCDATA as follows: @TM$RUN.BUFMAKE query mode = off translate type = x_common ; subtype = empsvcdata ; infile = myfile*forms.empsvc/cob ; outfile = myfile*forms. ; 7833 5080 009 3 41

Buffer Subtypes exit input_language = cobol ; output_language = cobol-85 ; interface = general ; store_translation = no Example 3 9. BUFMAKE Execution The output file myfile*forms now contains an Open Distributed Transaction Processing VIEW in element empsvcdata/view. This VIEW is shown in Example 3-11. The input data structure for the BUFMAKE processor is shown in Example 3-10. Example of BUFMAKE Input You can use this input from an existing COBOL program Working Storage Section to create a VIEW that can be used as a starting point for defining data structures for Open Distributed Transaction Processing clients and services. **************************************************************** * WORKING-STORAGE SECTION. * SQL BEGIN DECLARE SECTION. **************************************************************** 01 SQLCODE PIC S9(9) USAGE COMPUTATIONAL. 01 RDMCA. 02 ERROR-STATUS PIC 9(4). 02 AUX-INFO PIC S9(9) BINARY. 01 ENUM PIC 9(4). 01 ESSN PIC 9(10). 01 ELNAME PIC X(30). 01 EFNAME PIC X(30). 01 EBD PIC 9(7). 01 ENUM1 PIC 9(4). 01 ESSN1 PIC 9(10). 01 ELNAME1 PIC X(30). 01 EFNAME1 PIC X(30). 01 EBD1 PIC 9(7). 01 AUX-TEXT PIC X(60). 01 SDATA PIC X(50) VALUE SPACES. 01 RDATA PIC X(50) VALUE SPACES. Example 3 10. BUFMAKE Input When examining the VIEW in the example, you will see fields preceding and following the user data fields. These fields were added by BUFMAKE for passing PID information and Display Processing System information between the client and service programs. Descriptions of the additional fields precede the examples. 3 42 7833 5080 009

Buffer Subtypes Additional BUFMAKE Output The general interface and the Display Processing System interface to the Heritage Application Access software require additional information beyond that supplied to the BUFMAKE processor when translation is needed. This additional information is provided at the beginning of the user data fields in the output VIEWs, C header files, and COBOL COPY files. The following table shows those fields that precede the user data fields in the VIEWs, C header files, and COBOL COPY files produced by the BUFMAKE processor when INTERFACE=GENERAL. Table 3 5. Additional Data Fields That Precede User Data Fields Field Name haa_trans_level haa_pid_command haa_pid_value haa_pid_key Description An integer containing the BUFMAKE translation level for this generated header file. An integer containing the PID usage command for heritage application program execution. An integer containing the PID value for heritage application program execution. An integer containing the PID key for heritage application program execution. See the Heritage Application Access Administration and Programming Guide for more information about the use of these fields. Note: If you are not developing HAA applications, delete these additional fields from your VIEW. The COBOL COPY file or C header file output by BUFMAKE may also hold some additional fields named HAA-FILLER-#, where # is a number. These fields can be removed. Additional BUFMAKE Output When INTERFACE=DPS The Display Processing System interface to the Heritage Application Access software requires additional information beyond that supplied to the BUFMAKE processor. Some of this additional information is provided at the front of the user data fields in the output VIEWs, C header files, or COBOL COPY files and the rest of it is provided following the user data fields. Note: If you are not developing HAA applications, delete these additional fields from your VIEW. The COBOL COPY file or C header file output by BUFMAKE may also hold some additional fields named HAA-FILLER-#, where # is a number. These fields can be removed. 7833 5080 009 3 43

Buffer Subtypes Example of BUFMAKE Output This VIEW was created by BUFMAKE from the variables extracted from the sample program source code: VIEW EMPSVCDATA # type cname fbname count # ----- -------------------------- ---------------------- ----- long haa_trans_level HAA_TRANS_LEVEL 1 long haa_pid_command HAA_PID_COMMAND 1 long haa_pid_value HAA_PID_VALUE 1 long haa_pid_key HAA_PID_KEY 1 long sqlcode SQLCODE 1 char error_status ERROR_STATUS 4 long aux_info AUX_INFO 1 char enum ENUM 4 char essn ESSN 10 char elname ELNAME 30 char efname EFNAME 30 char ebd EBD 7 char enum1 ENUM1 4 char essn1 ESSN1 10 char elname1 ELNAME1 30 char efname1 EFNAME1 30 char ebd1 EBD1 7 char aux_text AUX_TEXT 60 char sdata SDATA 50 char rdata RDATA 50 END Example 3 11. BUFMAKE VIEW Note: If you are not developing HAA applications, delete the HAA variables (denoted by shading) from your VIEW. Once you have edited the VIEW for your needs, use the VADD utility to generate the C header files and COBOL COPY files, and install the VIEW definitions in the Type Directory. 3.3.6. Comparing BUFMAKE and VADD Both the BUFMAKE and VADD processors produce VIEWs, C header files, and COBOL COPY files as part of their output and both write to directories in the Open Distributed Transaction Processing FGSS. Because of these similarities, the two processors are sometimes confused. The purpose of this subsection is to clarify the unique role of each processor. 3 44 7833 5080 009

Buffer Subtypes BUFMAKE and VADD Diagram The following figure shows the relationship of BUFMAKE and VADD to Open Distributed Transaction Processing and to one another. Open DTP Transaction Manager FGSS BUFMAKE Heritage Application Access Translation Directory Open DTP Type Directory VADD Standard Programming Language Variables VIEW Header and COPY Files Header and COPY Files Figure 3 3. BUFMAKE and VADD Processors and the Open Distributed Transaction Processing FGSS BUFMAKE Purpose BUFMAKE was originally created for the Heritage Application Access environment to aid the translation of existing program data for the client/server environment. BUFMAKE is the utility processor you use to create VIEWs using your existing program's I/O buffers. The BUFMAKE processor reads the standard programming language data definition for an I/O buffer and chooses the most appropriate VIEW data type for each buffer variable. 7833 5080 009 3 45

Buffer Subtypes VADD Purpose The VADD processor is the VIEW compiler for OS 2200 systems. VADD processes VIEWs to install buffer subtype definitions in an Open Distributed Transaction Processing repository called the Type Directory. VADD also generates C header files and COBOL COPY files for inclusion in the client and service application programs. Open Distributed Transaction Processing uses the buffer subtype information stored in the Type Directory for validating buffer subtypes when processing service requests. It also uses the Type Directory information for data encoding and decoding when passing data between systems with heterogeneous architectures. (See 3.2.1 for more information on the VADD processor). When you develop a new Open Distributed Transaction Processing service routine, you may choose to use X_COMMON and X_C_TYPE typed buffers for the service's input and output. You design the new service's I/O buffers by creating one or more VIEWs. You execute the VADD processor to install the VIEWs and generate C header files or COBOL COPY files. Your new service program references its I/O data by including the C header files or COBOL COPY files generated by VADD. Illustrating the BUFMAKE and VADD Roles This example illustrates the unique roles played by VADD and BUFMAKE. Suppose you want to convert a Display Processing System COBOL application program to a new Open Distributed Transaction Processing service and you wish to access this new service from a new client program executing on a PC. You would: 1. Determine the buffer types your application program uses. For this example, you chose X_COMMON. 2. Acquire the I/O requirements from your application program source code. You determined the program in this example uses a Display Processing System form as its sole input and output. 3. Translate the I/O requirements into Open Distributed Transaction Processing VIEWs using the BUFMAKE processor. You executed the BUFMAKE processor using the Display Processing System form's Working Storage procedure as input. BUFMAKE generated a VIEW for you. You may use this VIEW as a starting point to define data variables for your new service. 4. Configure and use your new service routine. You executed the VADD processor to install the VIEW into the type directory. You copied the VIEW to the PC and installed it using the VIEW compiler provided for the PC. You executed the TMSCON processor to configure the new service. 3 46 7833 5080 009

Buffer Subtypes When your PC client program issues a service request to service, Open Distributed Transaction Processing validates the buffer subtype and translates the data from the PC data architecture into the corresponding data format required by the OS 2200 system. Open Distributed Transaction Processing performs this validation and translation using the buffer subtype information stored in the Type Directory by the VADD processor. For example, Open Distributed Transaction Processing uses the buffer subtype definition to translate the ASCII character fields from the 8-bit bytes used on the PC to the 9-bit bytes required by the OS 2200 system. C Header Files and COBOL COPY Files Both the BUFMAKE and VADD processors produce C headers files and COBOL COPY files for use by client programs executing on OS 2200 systems. You can include the C header file or the COBOL COPY file from either processor in your OS 2200 client program. However, BUFMAKE provides the advantage of properly initialized fields by producing C header files and COBOL COPY files that contain all initial values present in your input variable declarations. For more information see the Heritage Application Access Administration and Programming Guide. 7833 5080 009 3 47

Buffer Subtypes 3 48 7833 5080 009

Section 4 Building Java Clients This section contains the following topics. Topic Description Reference Using the JMAC Utility Example JMAC call and output General procedures for using the JMAC utility; JMAC utility call format and options; MAKECLIENT runstream output Complete example of input to the JMAC utility and the output runstream to build a Java client 4.1 4.2 4.1. Using the JMAC Utility The JMAC (Java make a client) utility is a processor that creates a runstream (addstream) of Executive Control Language (ECL) statements that call OS 2200 tools to build a Java client. The runstream name produced by the JMAC utility is stored with the name MAKECLIENT. (You can store the output with a different name by supplying an output name on the call to the JMAC utility.) When you use the @ADD statement to execute the MAKECLIENT runstream, the MAKECLIENT runstream Creates all application-dependent client components Statically links the Java client The JMAC utility is used to build extended mode batch and demand clients. Modifying JMAC Output When it generates the MAKECLIENT addstream, the JMAC utility references JMAC processor call options you specify A make-form structure of parameters that you build to specify Characteristics of Java client programs Other classes and files associated with the clients 7833 5080 009 4 1

Building Java Clients If your make-form information is incomplete, the JMAC utility uses default values and makes some assumptions about your application development environment. As a result, you may have to modify the MAKECLIENT addstream, depending on your application development environment. Using the Meta-Assembler (MASM) Processor The MAKECLIENT runstream that builds a Java client calls the MASM processor. For the extended mode processing environment, Unisys restricts support for MASM to those processes specifically described in user documentation. The following note summarizes Unisys policy regarding support for MASM usage. Note: Unisys supports extended mode MASM usage (assembler directive $EXTEND with or without assembler directive $OBJ) only in software written by Unisys or in interfaces written by the customer that explicitly require extended mode assembler-produced elements according to the documentation written by Unisys. In a nonextended mode MASM usage (absence of assembler directive $EXTEND), Unisys does not support the generation of object modules (use of assembler directive $OBJ) but will continue to provide full support for the generation of other provided element types that are not object modules (absence of both the $EXTEND and $OBJ assembler directives). Ordinarily, you should not need to modify portions of MAKECLIENT runstreams that call the MASM processor. Contents This subsection contains the following topics. Topic Description Reference Procedure for building Java clients Building the makeform input Calling the JMAC utility Outline of steps to prepare JMAC input, call the processor, and build a client Structure, content, and syntax rules for the make-form input structure you provide on the call to the JMAC utility Format and options for calling the JMAC utility to produce a MAKECLIENT runstream 4.1.1 4.1.2 4.1.3 4 2 7833 5080 009

Building Java Clients 4.1.1. Procedures for Building Java Clients To use the JMAC utility to build any type of Java client, follow the steps outlined in the following table. Table 4 1. Steps to Build a Client Step Task Reference 1 Build a make-form component that provides input client information used by the JMAC utility. 2 Call the JMAC utility. Use the make-form structure you created as input. 3 If necessary, modify the MAKECLIENT addstream to suit your own environment and application needs. 4 Use the @ADD statement to execute the MAKECLIENT runstream from either a demand run or a batch run. If you store the JMAC output in the default MAKECLIENT temporary data file, the statement to execute MAKECLIENT is @ADD MAKECLIENT. (If you substitute a different filename on the JMAC call, use the @ADD statement to execute that file instead.) Note: If you execute MAKECLIENT from a batch run, be sure the MAKECLIENT file is accessible from the batch run. If you need the output elements from MAKECLIENT after the batch run completes, modify MAKECLIENT to place the output elements in cataloged files. 4.1.2 4.1.3 Section 5 Section 6 4.1.2. Building the Make-Form Input You supply Java client generation parameters using the make-form input structure. Create a make-form for a client in an OS 2200 data file or symbolic element. Structure and Syntax of Make-Form The general make-form structure is as follows (components are described in the following subsections): parameter-name1 value1 parameter-name2 value2... The following general syntax rules apply to a make-form structure: A make-form line is free-format and can be up to 132 characters long. Comment lines in a make-form structure are preceded by the # character. All characters from the # character to the end of the line are ignored. 7833 5080 009 4 3

Building Java Clients Parameter The make-form specifies the general parameters required to make a Java client. Table 4 2. Make-Form Parameter Values Parameter Name APIPATH CLASS INC JOPTION Description This parameter specifies the path where the package which contains the Transaction Manager APIs (/com/unisys/os2200/tmapi) is located. This parameter can be up to 120 characters long. APIPATH /JAVA/OPENDTP This parameter specifies a JAVA class file to be included in the link. If a path is specified before the class name, the USERPATH parameter is overridden. This parameter can be entered as many times as necessary to include all the required classes. However, the first class entered is assumed by the JLINK processor to be the starting program and must include "public static void main...". CLASS CLASS /JAVA/OPENDTP/CLASSES/JAVACLIENT.CLASS JAVAVIEW.CLASS This parameter specifies where to find any other elements, such as COMs, that need to be included in the link. This parameter can be entered as many times as necessary to include all the required files. INC INC INC INC MY*FILE. MY*FILE.ELEMENT1 TEMP. LOCAL The first INC type includes all elements in the file MY*FILE. The second INC type includes only ELEMENT1 from MY*FILE. The third INC type includes all elements from TEMP. The fourth INC type includes the element LOCAL from TPF$. Note: When a filename is specified without a qualifier, a period must be included following the file name. Otherwise, the file type is interpreted as an element. This parameter specifies any special option to be included in the JLINK of the client. This parameter can be specified multiple times to specify multiple JOPTIONs for a JLINK. For more information on the JOPTION parameter, see the Virtual Machine for the Java Platform on ClearPath OS 2200 User Guide. JOPTION -Djava.class.path=/java/mydir/myclasses 4 4 7833 5080 009

Building Java Clients Table 4 2. Make-Form Parameter Values Parameter Name USERPATH XQT Description This parameter specifies where the user class files are located. This value can be overridden by a path specified in the CLASS parameter. This parameter can be up to 120 characters long. USERPATH /JAVA/OPENDTP/CLASSES This parameter specifies where the output zoom will be placed. XQT MY*XQT 4.1.3. Calling the JMAC Utility The call to the JMAC utility has the following format: @OTM$*TM$UTIL.JMAC[,options] [input][,[output][,[client-name][,otm-qual]]] [make-form] @EOF where: options is one or both of the following letter options. Option H N Action Display help. Do not echo the make-form structure. input is the name of the OS 2200 file or element that contains the make-form structure. If input is omitted, the make-form structure is read from the standard input stream (READ$). output is the name of the OS 2200 file or element that receives the MAKECLIENT addstream generated by the JMAC utility. If output is omitted, the MAKECLIENT addstream is written to a temporary data file named MAKECLIENT. 7833 5080 009 4 5

Building Java Clients client-name is the name of your client. This name must match the name configured in the TMSCONFIG file. It can be from 1 to 12 characters in length and can contain characters from among Uppercase letters A through Z Lowercase letters a through z Digits 0 through 9 The underscore character ( _ ) The dollar sign ( $ ) The default name is AP$GENERIC. otm-qual is the qualifier for the OLTP-2200 installation files. The otm-qual parameter is placed on @USE statements written to MAKECLIENT. The default is OTM$. make-form contains one or more user-supplied client generation parameters in the following format (described in 3.1.2): parameter-name1 value1 parameter-name2 value2... The parameters are described in 4.1.2. The only required parameter is the CLASS parameter which holds the value for the name of the main client program. See 4.2 for an example JMAC call and output. 4.2. Example JMAC Call and Output The following example shows an execution of the JMAC utility that creates a MAKECLIENT addstream for a Java batch client called myclient. Numbered explanations follow the example. The second example shows the resulting addstream. (1) @OTM$*TM$UTIL.JMAC,N,,myclient (2) APIPATH /JAVA/MYAPIPATH/ USERPATH /JAVA/MYPATH/ XQT MY*XQTFILE. INC MY*FILE.ELEMENT JOPTION -Djava.class.path=/java/myviewdir CLASS MYCLIENT.CLASS CLASS /JAVA/CLASSES/OTHERCLASS.CLASS @EOF OLTP-TM2200 JMAC 6R1 -- Wed Jul 12 08:59:38 2000 4 6 7833 5080 009

Building Java Clients *REMARK: Addstream to build client "myclient" is in file "MAKECLIENT." END JMAC. ERRORS: 0 WARNINGS: 0 Explanation Example 4 1. JMAC Call (1) @OTM$*TM$UTIL.JMAC,N,,myclient This executes the JMAC utility to create a Java batch client named myclient. (2) APIPATH /JAVA/MYAPIPATH/ USERPATH /JAVA/MYPATH/ XQT MY*XQTFILE. INC MY*FILE.ELEMENT JOPTION -Djava.class.path=/java/myviewdir CLASS MYCLIENT.CLASS CLASS /JAVA/CLASSES/OTHERCLASS.CLASS These are the make-form entries. These entries describe the client that is to be built. The following example shows the MAKECLIENT addstream produced as a result of the JMAC call in the preceding example. Explanations follow the example. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL (1) @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT EXTENDED (2) APNAME myclient OUTPUT FILE,TLIB$ VERSION,O @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$LIB,OTM$*TM$LIB @USE LOCAL$,TM$UTIL @USE RTS$,SYS$LIB$*EMOMRTS (3) @JLINK,MY*XQTFILE.myclient JINCLUDE /JAVA/MYPATH/MYCLIENT.CLASS JINCLUDE /JAVA/CLASSES/OTHERCLASS.CLASS JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TransactionTP.class JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TransactionTX.class JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TransactionTP$Buffer.class JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TransactionTX$Information$XID.c lass JINCLUDE 7833 5080 009 4 7

Building Java Clients /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TransactionTX$Information.class JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TransactionView.class JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TPException.class JINCLUDE /JAVA/MYAPIPATH/com/unisys/os2200/TMAPI/TXException.class JOPTION -Djava.class.path=/java/myviewdir INCLUDE TM$LIB.TRANSACTIONC/O INCLUDE TLIB$.AP$NAME/O INCLUDE MY*FILE.ELEMENT RESOLVE ALL REFERENCES USING TM$LIB, RTS$, LCN PROCESS FOR EXTENDED ZOOM DELETE ALL DEFINITIONS EXCEPT START$, (4) 'Java_com_unisys_os2200_TMAPI_TransactionTP_getbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getlong', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbytes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setlong', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpacall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpalloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcancel', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpdisconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpfree', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpgetreply', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tprealloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpreceive', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpsend', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tptypes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpurcodeget' 'Java_com_unisys_os2200_TMAPI_TransactionTX_txbegin', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txclose', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txcommit', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txgetinfo', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txopen', 4 8 7833 5080 009

Building Java Clients 'Java_com_unisys_os2200_TMAPI_TransactionTX_txrollback', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetcontrol', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetreturn', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsettimeout', @eof @. *****END OF CLIENT LINK***** Explanation Example 4 2. MAKECLIENT Addstream (1) @ADD TM$UTIL.MAKEAP$NAME Executes the MAKEAP$NAME utility that generates and assembles the AP$NAME element. The AP$NAME element contains the name of the client and a 63 word buffer for communicating with UDS. (2) APNAME myclient Contains the client name specified on the JMAC call. If you omit the client name on the call, the default name AP$GENERIC is used. (3) @JLINK,MY*XQTFILE.myclient JLINKs the client. The output objects module is placed in the specified XQT file, MY*XQTFILE. (4) 'Java_com_unisys_os2200_TMAPI_TransactionTP_getbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getlong', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbytes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setlong', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpacall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpalloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcancel', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpconnect', 7833 5080 009 4 9

Building Java Clients 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpdisconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpfree', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpgetreply', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tprealloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpreceive', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpsend', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tptypes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpurcodeget' 'Java_com_unisys_os2200_TMAPI_TransactionTX_txbegin', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txclose', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txcommit', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txgetinfo', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txopen', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txrollback', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetcontrol', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetreturn', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsettimeout', Lists the entry points in TMAPI package. Note: To resolve the reference to MCB$ENT from code module SYS$LIB$*JVM$LIB.STARTJVM/NODB, you have to edit the generated MAKECLIENT addstream and insert a use name of link$pf on file sys$lib$*app$<n> at the top of the stream. Where <n> represents an application group number. 4 10 7833 5080 009

Section 5 Building Servers Open Distributed Transaction Processing supports these types of servers for both extended mode and basic mode environments: High-Volume Transaction Processing (HVTIP) Transaction Processing (TIP) Batch This section describes Procedures for using the MAS (make a server) utility to build servers of all types Methods for starting servers This section contains the following topics. Topic Description Reference Using the MAS utility Example MAS call and output Starting servers General procedures for using the MAS utility; MAS utility call format and options; MAKESERVER runstream output Complete example of input to the MAS utility and the output runstream to build an extended mode batch server Methods to start different types of servers manually or by using server dispatcher features 5.1 5.2 5.3 Detailed information about building specific types of servers is in the following sections: Extended mode servers (see Section 6) Basic mode servers (see Section 7) Note: The Open Distributed Transaction Processing toolkit file is delivered on the OLTP-TM2200 release tape and contains examples that can help administrators and developers perform their tasks. See the Open Distributed Transaction Processing Administration Guide Volume 1 for a description of the toolkit and an explanation of how to use the sets of examples. 7833 5080 009 5 1

Building Servers 5.1. Using the MAS Utility The MAS utility is a processor that creates a runstream (addstream) of Executive Control Language (ECL) statements that call OS 2200 tools to build a server. The runstream name produced by the MAS utility is stored with the name MAKESERVER. (You can store the output with a different name by supplying an output name on the call to the MAS utility.) When you use the @ADD statement to execute the MAKESERVER runstream, the MAKESERVER runstream Creates all application-dependent server components Statically links (or maps) the server Note: In describing the actions that build a server application, this guide uses the term "static linking" to refer to either static linking by the LINK Processor (extended mode) or mapping by the Collector (basic mode). You can use the MAS utility to build extended mode and basic mode servers of all supported types (HVTIP, TIP, and batch). Modifying MAS Output When it generates the MAKESERVER addstream, the MAS utility references MAS processor call options you specify A make-form structure of parameters that you build to specify Characteristics of server programs Services associated with servers If your make-form information is incomplete, the MAS utility uses default values and makes some assumptions about your application development environment. As a result, you may have to modify the MAKESERVER addstream, depending on the type of server and your application development environment. Using the Meta-Assembler (MASM) Processor The MAKESERVER runstream that builds a server calls the MASM processor. For the extended mode processing environment, Unisys restricts support for MASM to those processes specifically described in user documentation. The following note summarizes Unisys policy regarding support for MASM usage. 5 2 7833 5080 009

Building Servers Note: Unisys supports extended mode MASM usage (assembler directive $EXTEND with or without assembler directive $OBJ) only in software written by Unisys or in interfaces written by the customer that explicitly require extended mode assembler-produced elements according to the documentation written by Unisys. In a nonextended mode MASM usage (absence of assembler directive $EXTEND), Unisys does not support the generation of object modules (use of assembler directive $OBJ) but will continue to provide full support for the generation of other provided element types that are not object modules (absence of both the $EXTEND and $OBJ assembler directives). Ordinarily, you should not need to modify portions of MAKESERVER runstreams that call the MASM processor. Contents This subsection contains the following topics: Topic Description Reference Procedure for building servers Building the makeform input Calling the MAS utility Outline of steps to prepare MAS input, call the processor, and build a server Structure, content, and syntax rules for the make-form input structure you provide on the call to the MAS utility Format and options for calling the MAS utility to produce a MAKESERVER runstream 5.1.1 5.1.2 5.1.3 5.1.1. Procedures for Building Servers To use the MAS utility to build any type of server, follow the steps outlined in the following table. Table 5 1. Steps to Build a Server Step Task Reference 1 Build a make-form component that provides input server information used by the MAS utility. 2 Call the MAS utility. Use the make-form structure you created as input. Specify the options you need to build the type of server you want. 3 If necessary, modify the MAKESERVER addstream to suit your own environment and application needs. 5.1.2 5.1.3 7833 5080 009 5 3

Building Servers Table 5 1. Steps to Build a Server Step Task Reference 4 Use the @ADD statement to execute the MAKESERVER runstream from either a demand run or a batch run. If you store the MAS output in the default MAKESERVER temporary data file, the statement to execute MAKESERVER is @ADD MAKESERVER. (If you substitute a different filename on the MAS call, use the @ADD statement to execute that file instead.) Note: If you execute MAKESERVER from a batch run, be sure the MAKESERVER file is accessible from the batch run. If you need the output elements from MAKESERVER after the batch run completes, modify MAKESERVER to place the output elements in cataloged files. 5 Depending on the type of server you are building, copy the server files created by MAKESERVER into the appropriate library. For example, you must install HVTIP server components in an HVTIP library. Section 6 Section 7 Section 6 Section 7 5.1.2. Building the Make-Form Input You supply server generation parameters using the make-form input structure. Create a make-form for a server in an OS 2200 data file or symbolic element. Structure and Syntax of Make-Form The general make-form structure is as follows (components are described in the following subsections): [*PARAMETERS parameter-table] [*FILES file-table] [*ROUTINES service-routine-table] The following general syntax rules apply to a make-form structure: Each table identifier (*PARAMETERS, *FILES, and *ROUTINES) must be on a separate line. A make-form line is free-format and can be up to 132 characters long. Comment lines in a make-form structure are preceded by the # character. All characters from the # character to the end of the line are ignored. The *ROUTINES table is required for USC C, USC COBOL, and ASCII COBOL servers. 5 4 7833 5080 009

Building Servers Parameter Table The make-form parameter table specifies the general parameters required to make a server. A parameter table has the following format: parameter-name1 value1 parameter-name2 value2... You can specify the following parameter names and values. Table 5 2. Make-Form Parameter Table Values Parameter Name DBBANKSIZE MEMBLOCKS TPSVRDONE TPSVRINIT Description An integer that specifies the number of words of DBANK storage required by the server. This parameter applies only to ASCII COBOL HVTIP servers. If not specified, the default value is the same as the default for the DBANK SGS for the MAPHVTIP SSG skeleton provided in the ASCII COBOL TIP library. For example DBANKSIZE 20 An integer that specifies the number of 512-word blocks of DBANK memory required by the server. This parameter applies only to ASCII COBOL TIP servers. The default value is 10 (5,120 words). For example MEMBLOCKS 20 A string that specifies the element name and optional version name of the user TPSVRDONE final processing routine. The default value is the TPSVRDONE routine in the TM$UTIL file. For example TPSVRDONE MYSVRDONE/OM A string that specifies the element name and optional version name of the user TPSVRINIT initial processing routine. The default value is the TPSVRINIT routine in the TM$UTIL file. For example TPSVRINIT MYSVRINIT/OM File Table The make-form file table specifies the names of library and user files required to make a server. A file table has the following format: file-type1 file-name1 file-type2 file-name2... where: file-type is a predefined mnemonic representing a kind of file, as follows. 7833 5080 009 5 5

Building Servers Table 5 3. Make-Form File Table Value File Type ACOB ACOBTIP AP APIPATH CLASS INC Description Specifies the name of the ASCII COBOL library file. This file type applies only to ASCII COBOL servers. The default value is SYS$LIBS*ACOB. For example ACOB MY*ACOB Specifies the name of the ASCII COBOL TIP relocatable library file. This file type applies only to ASCII COBOL TIP and HVTIP servers. The default value is SYS$LIBS*ACOB-TIP. For example ACOBTIP MY*ACOB-TIP Specifies the file that contains the compiled service routine object module or relocatable elements. This file type applies only to TIP and batch servers. The default value is TPF$. For example AP MY*WORKFILE This parameter specifies the path where the package which contains the Transaction Manager APIs (/com/unisys/os2200/tmapi) is located. Can be up to 120 characters long. This file type applies only to Java servers. For example APIPATH /JAVA/OPENDTP This parameter specifies a Java class file to be included in the link. If a path is specified before the class name, the USERPATH parameter is overridden. This file type applies only to Java servers. This parameter can be entered as many times as necessary to include all the required classes. CLASS CLASS /JAVA/OPENDTP/CLASSES/SERVICE.CLASS JAVAVIEW.CLASS Specifies a user file or element to be linked by the LINK processor. The INC file type is allowed only for extended mode servers. Multiple entries are allowed for this file type. There is no default. For example INC MY*WORKFILE. INC MY*TEMPFILE.CLIENT/C INC TEMP. INC LOCAL The first INC type includes all elements in the file MY*WORKFILE. The second INC type includes only MY*TEMPFILE.CLIENT/C. The third INC type includes all elements from MY*TEMP. The fourth INC type includes the element LOCAL from TPF$. Note: When a filename is specified without a qualifier, a period must be included following the filename. Otherwise, the file type is interpreted as an element. 5 6 7833 5080 009

Building Servers Table 5 3. Make-Form File Table Value File Type JOPTION LOCAL TIP USERPATH XQT Description This parameter specifies any special option to be included in the JLINK of the server. This file type applies only to Java servers. For more information on the JOPTION parameter, see the Virtual Machine for the Java Platform on ClearPath OS 2200 User Guide. This parameter can be entered multiple times to specify multiple JOPTION s for a JLINK. JOPTION -Djava.class.path=/java/mydir/myclasses Specifies the file that contains the compiled TPSVRINIT and TPSVRDONE routines. The default is the TM$UTIL file. For example LOCAL MY*LOCALCODE Specifies the library file that contains the TIP primitives. This file type applies only to ASCII COBOL TIP and HVTIP servers. The default value is TIP$*TIPLIB$. For example TIP MY*TIPLIB$ This parameter specifies where the user class files are located. This value can be overridden by a path specified in the CLASS parameter. Can be up to 120 characters long. This file type applies only to Java servers. For example USERPATH /JAVA/OPENDTP/CLASSES Specifies the file in which the linked server executable element (ZOOM or absolute) is placed. The default is TPF$. For example XQT MY*XQT. file-name is an unbroken character string that specifies a filename. The file-name does not have to be enclosed in quotation marks. However for the INC type, the file-name can be either a file or an element. Service Routine Table The make-form service routine table specifies the name and other information about each service routine the server can call. A service routine table has the following format: service-routine-entry-1 service-routine-entry-2... A service-routine-entry has the following format: scode svc-routine-name libno bankno [element[/version]] 7833 5080 009 5 7

Building Servers where: scode is the index for the service routine in the SREPTABLE. The SREPTABLE is an array that contains the entry point addresses of all service routines for the server. The scode is a number greater than or equal to zero; it corresponds to the scode configured in the *SERVICES section of the TMSCONFIG file. It is not necessary to specify consecutive scodes beginning at 0. Unused entries in the SREPTABLE are initialized with the entry point of SVCERR(), the error handler for the server main program. However, the SREPTABLE is smaller if you use consecutive scode values. svc-routine-name is the actual entry point name of the service routine. The entry point name does not have to match the name of a service configured in the TMSCONFIG file, unless you want the service and the service routine to have the same name. Note: For both C and COBOL service routines, the svc-routine-name must begin with an alphabetic character, not a digit. libno is the HVTIP library number of the service routine. This parameter is used only for building HVTIP servers. If you are building a TIP or batch server, you must use a filler value, such as a hyphen ( - ), for this parameter. bankno is the bank number of the service routine. This parameter is used only for building HVTIP servers. If you are building a TIP or batch server, you must use a filler value, such as a hyphen ( - ), for this parameter. element is the name of the element that contains the compiled version of the service routine. If element is omitted, the @LINK (or @MAP) statements written to MAKESERVER do not contain an INCLUDE (or IN) statement for the service routine. This field does not apply to HVTIP servers; if you are building an HVTIP server, leave this field empty. version is the name of the version of the element that contains the compiled version of the service routine. The version parameter is optional if element is specified. This field does not apply to HVTIP servers; if you are building an HVTIP server, leave this field empty. 5 8 7833 5080 009

Building Servers 5.1.3. Calling the MAS Utility The call to the MAS utility has the following format: @OTM$*TM$UTIL.MAS[,options] [input][,[output][,[server-name][,otm-qual]]] [make-form] @EOF where: options is one or more of the following letter options. Note: Calling the MAS utility without options produces a MAKESERVER runstream to build a C Compiler extended mode batch server. Select the options that generate a server matching the service programming language and desired run mode. Option A B C G H J N R T U V Action Generate MAKESERVER for an ASCII COBOL server. Generate MAKESERVER for a batch mode server (default). Generate MAKESERVER for a C server (default). Generate MAKESERVER, which creates a server with the nested call feature enabled. Refer to the Open Distributed Transaction Processing Programming Guide for more information about the nested call feature. This option is not allowed with the J option. Display help. Generate MAKESERVER for a Java server. The J option is only for Java Batch servers and can only be used with the B option. Do not echo the make-form structure. Generate MAKESERVER for a reentrant ASCII COBOL TIP server (when used with options A and T). Generate MAKESERVER for a TIP server. Generate MAKESERVER for a COBOL server using C tpsvrinit and tpsvrdone functions. See the Y option for using COBOL functions. Generate MAKESERVER for an HVTIP server. 7833 5080 009 5 9

Building Servers Option X Y Action Generate MAKESERVER for ASCII COBOL HVTIP server using SERVER$MAIN with COMMON-STORAGE SECTION (when used with options A and V). Generate MAKESERVER for a COBOL server using COBOL tpsvrinit and tpsvrdone functions (must be used with the U option). input is the name of the OS 2200 file or element that contains the make-form structure. If input is omitted, the make-form structure is read from the standard input stream (READ$). output is the name of the OS 2200 file or element that receives the MAKESERVER addstream generated by the MAS utility. If output is omitted, the MAKESERVER addstream is written to a temporary data file named MAKESERVER. server-name is the name of your server. This name must match the name configured in the TMSCONFIG file. It can be from 1 to 12 characters in length and can contain characters from among Uppercase letters A through Z Lowercase letters a through z Digits 0 through 9 The underscore character ( _ ) The dollar sign ( $ ) The default name is AP$GENERIC. Note: TIP and HVTIP servers generated with a default server name of AP$GENERIC cannot be used unless the name of the server executable is changed. The name of the executable must be specified in the NAM field of the VALTAB, which is limited to 6 characters. Special characters, including the dollar sign ($), are not allowed. otm-qual is the qualifier for the OLTP-2200 installation files. The otm-qual parameter is placed on @USE statements written to MAKESERVER. The default is OTM$. 5 10 7833 5080 009

Building Servers make-form contains one or more user-supplied server generation parameters in the following format (described in 5.1.2): [*PARAMETERS parameter-table] [*FILES file-table] [*ROUTINES service-routine-table] where: parameter-table specifies general parameters required to make a server. The parameter-table is optional, and default values are assumed if it is omitted. file-table defines the names of library and user files required to make a server. The filetable is optional, and default values are assumed if it is omitted. service-routine-table defines the name and other information about each service routine the server can call. The service routine table is required for C and COBOL; it must define at least one service routine. The service-routine-table is not required for Java servers. See 5.2 for an example MAS call and output. 5.2. MAS Examples The following examples show the MAS examples for the C, COBOL, and Java languages. 5.2.1. C and COBOL Example The following example shows an execution of the MAS utility that creates a MAKESERVER addstream for a C extended mode batch server called myserver. Numbered explanations follow the example. The second example shows the resulting addstream. (1) @OTM$*TM$UTIL.MAS,N,,myserver (2) *PARAMETERS # NAME VALUE # --------- ------------ TPSVRINIT MYSVRINIT/OM TPSVRDONE MYSVRDONE/OM # END OF PARAMETERS (3) *FILES # TYPE FILENAME 7833 5080 009 5 11

Building Servers # ------ -------- AP MY*WORK LOCAL MY*OTHERWORK XQT TPF$ # END OF FILES (4) *ROUTINES # SCODE SVC ROUTINE NAME LIBNO BANKNO ELT/VERSION # ----- ---------------- ----- ------ ----------- 0 sr_one - - SR-ONE/OM 1 sr_two - - SR-TWO/OM 2 sr_three - - SR-THREE/OM # END OF ROUTINES @EOF OLTP-TM2200 3R1 -- Fri Mar 8 14:19:03 1996 (5) *REMARK: B-option assumed: server execution environment is BATCH. *REMARK: C-option assumed: server language is UC. *REMARK: Addstream to build "myserver" is in file "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Explanation Example 5 1. C and COBOL MAS Call (1) @OTM$*TM$UTIL.MAS,JN,,jserver Executes the MAS utility to create a C extended mode batch server named myserver. Default values for the options parameter are used, as shown in (5). (2) *PARAMETERS Identifies the make-form parameters table. Parameter table entries follow this statement. (3) *FILES Identifies the make-form files table. File table entries follow this statement. (4) *ROUTINES Identifies the make-form routines table. Routine table entries follow this statement. (5) *REMARK: B-option assumed: server execution environment is BATCH. *REMARK: C-option assumed: server language is UC. Reflects the default option values used in the MAS call shown in (1). 5 12 7833 5080 009

Building Servers The following example shows the MAKESERVER addstream produced as a result of the MAS call in the preceding example. Explanations follow the example. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL. @USE UC$PF,OTM$*TM$LIB. @ASG,A UC$PF. (1) @UC,SI,TLIB$.SREPTABLE/O,,,NO-DEBUG #include "xatmi.h" extern void sr_one(tpsvcinfo *); extern void sr_two(tpsvcinfo *); extern void sr_three(tpsvcinfo *); (2) int hi_scode = 2; (3) int svr_type = 0; /* UC server void (*tpservice[])(tpsvcinfo *) = { sr_one, sr_two, sr_three }; @. *****END OF SREPTABLE***** (4) @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT EXTENDED (5) APNAME myserver OUTPUT FILE, TLIB$ VERSION,0 @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$LIB,OTM$*TM$LIB. @USE LOCAL$,MY*OTHERWORK. @USE AP$,MY*WORK. @USE RTS$,SYS$LIB$*EMOMRTS. (6) @LINK,LE,TPF$.myserver INCLUDE TM$UTIL.SERVER$MAIN/O INCLUDE TLIB$.AP$NAME/O INCLUDE TLIB$.SREPTABLE/O INCLUDE LOCAL$.MYSVRINIT/OM INCLUDE LOCAL$.MYSVRDONE/OM INCLUDE AP$.SR-ONE/OM INCLUDE AP$.SR-TWO/OM INCLUDE AP$.SR-THREE/OM RESOLVE ALL REFERENCES USING TM$LIB, RTS$, LCN PROCESS FOR EXTENDED DELETE ALL DEFINITIONS EXCEPT START$ @. *****END OF SERVER LINK***** Example 5 2. C and COBOL MAKESERVER Addstream 7833 5080 009 5 13

Building Servers Explanation (1) @UC,SI,TLIB$.SREPTABLE/O,,,NO-DEBUG Compiles the SREPTABLE. The SREPTABLE is a C data structure. A C Compiler is required to make both C and COBOL servers. (2) int hi_scode = 2; Tells the server main program the upper limit of the SREPTABLE. The hi_scode variable is shown here as an integer. (3) inst svr_type = 0; /*UC server Tells the server main program the language of the server. The svr_type variable is shown here as an integer. (4) @ADD TM$UTIL.MAKEAP$NAME Executes the MAKEAP$NAME utility that generates and assembles the AP$NAME element. The AP$NAME element contains the name of the server and a 63-word buffer for communicating with UDS. (5) APNAME myserver Contains the server name specified on the MAS call. If you omit the server name on the call, the default name AP$GENERIC is used. (If AP$GENERIC is used, this server must be identified in the TMSCONFIG file as AP$GENERIC.) (6) @LINK,LE,TPF$.myserver Links the server. The output object module is place in the specified XQT file, TPF$. 5.2.2. Java Example The following example shows an execution of the MAS utility that creates a MAKESERVER addstream for a Java server called jserver. Numbered explanations follow the example. The second example shows the resulting addstream. (1)@OTM$*TM$UTIL.MAS,JN,,jserver OLTP-TM2200 MAS 9R1 -- TUE AUG 17 17:47:25 2004 (2) *REMARK: B-OPTION ASSUMED: SERVER EXECUTION ENVIRONMENT IS BATCH. *REMARK: SERVER LANGUAGE IS JAVA. (3) *PARAMETERS # NAME VALUE # --------- -------- 5 14 7833 5080 009

Building Servers TPSVRINIT TPSVRDONE TPSVRINIT/O TPSVRDONE/O # END OF PARAMETERS (4) *FILES # TYPE FILENAME # -------- -------- APIPATH USERPATH XQT INC JOPTION CLASS CLASS /JAVA/APIPATH/ /JAVA/MYPATH/ MY*XQTFILE MY*FILE.ELEMENT -Djava.class.path=/java/myviewdir JSERVICE.CLASS /JAVA/CLASSES/OTHERCLASS.CLASS # END OF FILES *REMARK: ADDSTREAM TO BUILD SERVER "jserver" IS IN FILE "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Explanation Example 5 3. Java MAS Call (1) OTM$*TM$UTIL.MAS,JN,,jserver Executes the MAS utility to create a Java extended mode batch server named jserver. Default values for the options parameter are used. (2) *REMARK: B-OPTION ASSUMED: SERVER EXECUTION ENVIRONMENT IS BATCH. Reflects the default option value used in the MAS call shown in (1). (3) *PARAMETERS Identifies the make-form parameters table. Parameter table entries follow this statement. (4) *FILES Identifies the make-form files table. File table entries follow this statement. 7833 5080 009 5 15

Building Servers The following example shows the MAKESERVER addstream produced as a result of the MAS call in the preceding example. Explanations follow the example. @FREE TLIB$. @ASG,T TLIB$.,F///2000. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL @USE UC$PF,OTM$*TM$LIB @ASG,A UC$PF. (1) @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT EXTENDED (2) APNAME jserver OUTPUT FILE,TLIB$ VERSION,O @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$LIB,OTM$*TM$LIB @USE LOCAL$,TM$UTIL @USE AP$,TPF$ @USE RTS$,SYS$LIB$*EMOMRTS (3) @JLINK,F,MY*XQTFILE.jserver (4) JINCLUDE /JAVA/MYPATH/JSERVICE.CLASS JINCLUDE /JAVA/MYPATH/JSERVICE.CLASS JINCLUDE /JAVA/CLASSES/OTHERCLASS.CLASS JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionTP$Buffer.class JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionTP$ServiceInfo.class JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionTP.class JINCLUDE JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionTX$Information$XID.clas s JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionTX$Information.class 5 16 7833 5080 009

Building Servers JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionTX.class JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TransactionView.class JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TPException.class JINCLUDE /JAVA/APIPATH/com/unisys/os2200/TMAPI/TXException.class (5) JOPTION -Djava.class.path=/java/myviewdir INCLUDE TM$UTIL.SERVER$MAINJ/O INCLUDE TM$LIB.TRANSACTIONS/O INCLUDE TLIB$.AP$NAME/O INCLUDE LOCAL$.TPSVRINIT/O INCLUDE LOCAL$.TPSVRDONE/O INCLUDE MY*FILE.ELEMENT RESOLVE ALL REFERENCES USING SYS$LIB$*EMOMRTS., LOCAL_DEFS, LCN, TM$LIB. DELETE ALL DEFINITIONS EXCEPT START$, (6) 'Java_com_unisys_os2200_TMAPI_TransactionTP_getbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getlong', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbytes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setlong', 7833 5080 009 5 17

Building Servers 'Java_com_unisys_os2200_TMAPI_TransactionTP_setshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpacall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpalloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcancel', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpdisconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpfree', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpgetreply', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tprealloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpreceive', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpreturn', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpsend', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tptypes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpurcodeget', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txbegin', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txclose', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txcommit', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txgetinfo', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txopen', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txrollback', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetcontrol', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetreturn', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsettimeout' PROCESS FOR EXTENDED ZOOM @. *****END OF SERVER LINK***** Example 5 4. Java MAKESERVER Addstream 5 18 7833 5080 009

Building Servers Note: To resolve the reference to MCB$ENT from code module SYS$LIB$*JVM$LIB.STARTJVM/NODB, you have to edit the generated MAKESERVER addstream and insert a use name of link$pf on file sys$lib$*app$<n> at the top of the stream. Where <n> represents an application group number. Explanation (1) @ADD TM$UTIL.MAKEAP$NAME Executes the MAKEAP$NAME utility that generates and assembles the AP$NAME element. The AP$NAME element contains the name of the server and a 63 byte word for communicating with UDS. (2) APNAME jserver Contains server name specified on the MAS call. If you omit the server name, the default name AP$GENERIC is used. (3) @JLINK,F,MY*XQTFILE.jserver JLINKs the server. The F option causes the Java server code to be built as a UC funtion. The input object module is placed in the specified XQT file, MY*XQTFILE. (4) JINCLUDE/JAVA/MYPATH/JSERVICE.CLASS where/java/mypath/jservice.class is a CIFS path to a Java class file located in the CIFS directory. The JINCLUDE directive is interpreted by JLINK and passed on to LINK as an include. It is used to identify which Java class files to incorporate. JINCLUDE is documented in the Virtual Machine for the JavaTM Platform on ClearPath OS 2200 User Guide (7861 5739).. (5) JOPTION -Djava.class.path=/java/myviewdir The JOPTION directive is interpreted by JLINK. It is used to supply options at JLINK time to the Java launcher when the launcher is executed via a JLINK-produced OM Other standard and non-standard options are documented in the Virtual Machine for the JavaTM Platform on ClearPath OS 2200 User Guide (7861 5739). (6) 'Java_com_unisys_os2200_TMAPI_TransactionTP_getbyte' 'Java_com_unisys_os2200_TMAPI_TransactionTP_getdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_getlong', 7833 5080 009 5 19

Building Servers 'Java_com_unisys_os2200_TMAPI_TransactionTP_getshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbyte', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setbytes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setdouble', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setfloat', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setint', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setlong', 'Java_com_unisys_os2200_TMAPI_TransactionTP_setshort', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpacall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpalloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcall', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpcancel', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpdisconnect', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpfree', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpgetreply', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tprealloc', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpreceive', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpreturn', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpsend', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tptypes', 'Java_com_unisys_os2200_TMAPI_TransactionTP_tpurcodeget', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txbegin', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txclose', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txcommit', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txgetinfo', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txopen', 5 20 7833 5080 009

Building Servers 'Java_com_unisys_os2200_TMAPI_TransactionTX_txrollback', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetcontrol', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsetreturn', 'Java_com_unisys_os2200_TMAPI_TransactionTX_txsettimeout' Lists the entry points in the TMAPI package. 5.3. Starting Servers Start a server using the utility appropriate for the type of server execution. 5.3.1. Starting HVTIP and TIP Servers For normal production, the transaction manager automatically starts copies of HVTIP and TIP servers through the TMTSD server dispatcher utility (or the TSF processor, under certain conditions). You start the TMTSD utility through the TMSC processor. See the Open Distributed Transaction Processing Administration Guide Volume 1 for information about the TMSC processor, TMTSD server dispatcher utility, and TSF processor. You can also start a TIP or HVTIP server manually by entering its transaction code from a terminal opened to TIP. This method can be useful for handling special application problems or for testing; it is not intended for normal production. Note: You can more easily debug an HVTIP service routine by temporarily linking the service routine to a batch server. 5.3.2. Starting Batch Servers For normal production, the transaction manager automatically starts copies of batch servers through the TMBSD server dispatcher utility. You start the TMBSD utility through the TMSC processor. See the Open Distributed Transaction Processing Administration Guide Volume 1 for information about the TMSC processor and the TMBSD server dispatcher utility. Note: To use the TMBSD utility to start batch servers, you must create the runstreams needed to start your batch servers. You can also start a batch server manually by either Issuing an @START statement from an active run to start a batch runstream that executes the server Using the @XQT statement from a demand run, for example @XQT myserver 7833 5080 009 5 21

Building Servers No output is printed unless print statements are placed in the tpsvrinit() initial processing routine or tpsvrdone() final processing routine. Executing a batch server in demand mode is useful for debugging service routines. 5 22 7833 5080 009

Section 6 Extended Mode Servers This section provides additional information about extended mode servers for HVTIP, TIP, or batch mode execution: Listings of the components of different types of extended mode servers Examples of MAS MAKESERVER output to build different types of extended mode servers This section contains the following topics. Topic Description Reference Building an extended mode HVTIP server Building an extended mode TIP server Building an extended mode batch server Example of using the MAS utility; components of an extended mode HVTIP server Example of using the MAS utility; components of an extended mode TIP server Example of using the MAS utility; components of an extended mode batch server 6.1 6.2 6.3 More information about building and modifying servers is in the following sections: Procedures for using the MAS utility (see 5.1) Using your own initial and final processing routines to modify the execution of servers (see Section 8) 7833 5080 009 6 1

Extended Mode Servers 6.1. Building an Extended Mode HVTIP Server To build an extended mode HVTIP server, follow these steps: 1. Create a make-form for input to the MAS utility (see 5.1.2). 2. Call the MAS utility. Use the following options on the call to the MAS utility, depending on the programming language you are using: C language Use the C (C Compiler) and V (HVTIP) options, for example @OTM$*TM$UTIL.MAS,CV my*infile.,my*outfile.,myserver COBOL language Use the U (COBOL Compiler) and V (HVTIP) options, for example @OTM$*TM$UTIL.MAS,UV my*infile.,my*outfile.,myserver You can also include other options on the MAS utility call. See 6.1.3 for more information about the format and options of the MAS utility call. 3. (Optional) If your site has site-specific linking requirements, customize the MAKESERVER runstream accordingly. 4. Execute the MAKESERVER runstream produced by the MAS utility. The statement to execute MAKESERVER from a demand or batch run is @ADD MAKESERVER. If you execute MAKESERVER from a batch run, follow these guidelines: Be sure the batch run can access the MAKESERVER file. If you need to keep the output elements from MAKESERVER after the batch run completes, modify the MAKESERVER addstream to place those elements in cataloged files. 5. Create a VALTAB entry to register the HVTIP server. The M option in the VALTAB STATUS field is highly recommended for HVTIP server programs. Occasionally, the TIP system suspends scheduling of a transaction code to refresh internal data structures. Scheduling suspension stays in effect until currently executing programs terminate. An Open Distributed Transaction Processing HVTIP server program can execute indefinitely if you allow processing of multiple service requests with the MAX_TRANS and SVCTIMEOUT parameters in the Open Distributed Transaction Processing configuration. In this case, the scheduling suspension can cause some service requests to time out. The M option in VALTAB STATUS causes the TIP system to refresh the internal data structures without suspending scheduling. 6 2 7833 5080 009

Extended Mode Servers The RUN keyword on the VALTAB entry contains the estimated standard units of processing (SUPs). If a TIP/HVTIP server is configured with a large MAXTRANS value, it is possible for the server to use the maximum number of SUPs allowed, resulting in a PCT overflow error. Set the value of MAXTRANS to stop this instance of the server before the maximum number of SUPs is used. The COP keyword on the VALTAB entry should be greater than or equal to the value of the CONCURRENCY parameter for the server in the SERVERS section of the TMSCONFIG configuration file. If the value of the COP keyword is less than the value of CONCURRENCY, performance can be noticeably slower for the server when the CONCURRENCY value is reached. The REC keyword on the VALTAB entry can be used to specify options for MCB recoverable input messages. If your program will be configured with a group that has UDS specified as the resource manager and will be using MCB recoverable messages, be sure to verify that these settings are correct in your VALTAB entry. Open Distributed Transaction Processing will use the VALTAB settings during rollback processing if UDS is the resource manager. 6. Copy the object module created by MAKESERVER to the appropriate HVTIP library file, along with the object modules for the associated service routines. 6.1.1. Example MAS Call The following example creates an extended mode COBOL HVTIP server. The service routine names conform to the naming rules for COBOL subprograms. The MAKESERVER addstream generated is shown in 6.1.2. @OTM$*TM$UTIL.MAS,NUV,,myserver # SCODE SVC ROUTINE NAME LIBNO BANKNO # ----- ---------------- ----- ------ 0 COBSUB1 23 4 1 COBSUB2 24 6 2 COBSUB3 25 8 # END OF MAKE-FORM @EOF OLTP-TM2200 3R1 -- Fri Mar 8 14:19:03 1996 *REMARK: Server execution environment is HVTIP. *REMARK: Server language is UCOB. *REMARK: Addstream to build "myserver" is in file "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Example 6 1. MAS Input for a COBOL HVTIP Server 7833 5080 009 6 3

Extended Mode Servers 6.1.2. Example MAKESERVER Addstream The following example shows the MAKESERVER addstream generated by the MAS call in 6.1.1. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL @USE UC$PF,OTM$*TM$LIB @ASG,A UC$PF. @UC,SI,TLIB$.SREPTABLE/O,,,NO-DEBUG #include "xatmi.h" extern void COBSUB1(TPSVCINFO *); extern void COBSUB2(TPSVCINFO *); extern void COBSUB3(TPSVCINFO *); int hi_scode = 2; int svr_type = 1; /* UCOB server void (*tpservice[])(tpsvcinfo *) = { COBSUB1, COBSUB2, COBSUB3 }; @. *****END OF SREPTABLE***** @ADD TM$UTIL.MAKEAP$NAME 6 4 7833 5080 009

Extended Mode Servers ENVIRONMENT EXTENDED APNAME myserver OUTPUT FILE,TLIB$ VERSION,O @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE MASM$PF1,SYS$LIB$*LINK @ASG,A MASM$PF1. @MASM,SI,TLIB$.HVCALLS/O $OBJ. $ASCII. $INCLUDE 'HVTIP$CALLS'. $INCLUDE 'OM$DEF'. $INCLUDE 'SYS$*RLIB$.CBEP$$EMCALL'. $EXPORT 'COBSUB1',OM$ENTRY_DEF,SR0. $EXPORT 'COBSUB2',OM$ENTRY_DEF,SR1. $EXPORT 'COBSUB3',OM$ENTRY_DEF,SR2. SR0 HV$CALL 23,4,0. SR1 HV$CALL 24,6,0. SR2 HV$CALL 25,8,0. $END. @. *****END OF HVCALLS TABLE***** @USE TM$LIB,OTM$*TM$LIB @USE LOCAL$,TM$UTIL @USE RTS$,SYS$LIB$*EMOMRTS @LINK,LE,TPF$.myserver 7833 5080 009 6 5

Extended Mode Servers OUTPUT HVTIP INCLUDE TM$UTIL.C$JV/O. Must be first in the bank. INCLUDE TLIB$.HVCALLS/O INCLUDE TM$UTIL.SERVER$MAIN/O INCLUDE TLIB$.AP$NAME/O INCLUDE TLIB$.SREPTABLE/O INCLUDE LOCAL$.TPSVRINIT/O INCLUDE LOCAL$.TPSVRDONE/O RESOLVE ALL REFERENCES USING TM$LIB, RTS$, LCN DELETE ALL DEFINITIONS EXCEPT JUMPER @. *****END OF SERVER LINK***** Example 6 2. MAKESERVER Addstream for a COBOL HVTIP Server 6.1.3. Components of an Extended Mode HVTIP Server An extended mode HVTIP server has the following components. Table 6 1. Extended Mode HVTIP Server Components Component AP$NAME C$JV HVCALLS SERVER$MAIN Description Contains the name of the server and a 63-word buffer used to interface with UDS. AP$NAME does not contain any code. This element is generated by the MAKEAP$NAME utility within the MAKESERVER addstream. Contains the address of the server main program. It also allows execution to begin at main() rather than at tpsvrinit() code on return of a service routine. This component is in the TM$UTIL file. Defines the following for each service routine: Entry point name HVTIP library number Bank number The HVCALLS table is generated within the MAKESERVER addstream. Server main program for C and COBOL service routines. This component is stored in the TM$UTIL file. 6 6 7833 5080 009

Extended Mode Servers Table 6 1. Extended Mode HVTIP Server Components Component SREPTABLE tpsvrdone() routine tpsvrinit() routine Description An array containing the entry point address of each service routine. The server main program uses the scode as an index into this table to find each service routine. The SREPTABLE is generated in the MAKESERVER addstream. Final processing routine called by the server main program just before termination. A default version is in the TM$UTIL file; you can substitute your own version. Initial processing routine called by the server main program at the start of execution. A default version is in the TM$UTIL file; you can substitute your own version. 6.2. Building an Extended Mode TIP Server To build an extended mode TIP server, follow these steps: 1. Create a make-form for input to the MAS utility (see 5.1.2). 2. Call the MAS utility. Use the following options on the call to the MAS utility, depending on the programming language you are using: C language Use the C (C Compiler) and T (TIP) options, for example @OTM$*TM$UTIL.MAS,CT my*infile.,my*outfile.,myserver COBOL language Use the U (COBOL Compiler) and T (TIP) options, for example @OTM$*TM$UTIL.MAS,UT my*infile.,my*outfile.,myserver You can also include other options on the MAS utility call. See 5.1.3 for more information about the format and options of the MAS utility call. 3. (Optional) If your site has site-specific linking requirements, customize the MAKESERVER runstream accordingly. 4. Execute the MAKESERVER runstream produced by the MAS utility. The statement to execute MAKESERVER from a demand or batch run is @ADD MAKESERVER. If you execute MAKESERVER from a batch run Be sure the batch run can access the MAKESERVER file. If you need to keep the output elements from MAKESERVER after the batch run completes, modify the MAKESERVER addstream to place those elements in cataloged files. 7833 5080 009 6 7

Extended Mode Servers 5. Create a VALTAB entry to register the TIP server. The M option in the VALTAB STATUS field is highly recommended for TIP server programs. Occasionally, the TIP system suspends scheduling of a transaction code to refresh internal data structures. Scheduling suspension stays in effect until currently executing programs terminate. An Open Distributed Transaction Processing TIP server program can execute indefinitely if you allow processing of multiple service requests with the MAX_TRANS and SVCTIMEOUT parameters in the Open Distributed Transaction Processing configuration. In this case, the scheduling suspension can cause some service requests to time out. The M option in VALTAB STATUS causes the TIP system to refresh the internal data structures without suspending scheduling. The RUN keyword on the VALTAB entry contains the estimated standard units of processing (SUPs). If a TIP/HVTIP server is configured with a large MAXTRANS value, it is possible for the server to use the maximum number of SUPs allowed, resulting in a PCT overflow error. Set the value of MAXTRANS to stop this instance of the server before the maximum number of SUPs is used. The COP keyword on the VALTAB entry should be greater than or equal to the value of the CONCURRENCY parameter for the server in the SERVERS section of the TMSCONFIG configuration file. If the value of the COP keyword is less than the value of CONCURRENCY, performance can be noticeably slower for the server when the CONCURRENCY value is reached. The REC keyword on the VALTAB entry can be used to specify options for MCB recoverable input messages. If your program will be configured with a group that has UDS specified as the resource manager and will be using MCB recoverable messages, be sure to verify that these settings are correct in your VALTAB entry. Open Distributed Transaction Processing will use the VALTAB settings during rollback processing if UDS is the resource manager. 6. Copy the object module produced by MAKESERVER to the appropriate standard TIP program file. 6.2.1. Example MAS Call The following example creates an extended mode COBOL TIP server. The service routine names conform to the naming rules for COBOL subprograms. The MAKESERVER addstream generated is shown in 6.2.2. @OTM$*TM$UTIL.MAS,NUT,,myserver *FILES AP MY*WORK *ROUTINES # SCODE SVC ROUTINE NAME LIBNO BANKNO ELT/VERSION # ----- ---------------- ----- ------ ----------- 0 COBSUB1 - - SVC1 1 COBSUB2 - - SVC2 2 COBSUB3 - - SVC3 # END OF MAKE-FORM 6 8 7833 5080 009

Extended Mode Servers @EOF OLTP-TM2200 3R1 -- Fri Mar 8 14:19:03 1996 *REMARK: Server execution environment is TIP. *REMARK: Server language is UCOB. *REMARK: Addstream to build "myserver" is in file "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Example 6 3. MAS Input for a COBOL TIP Server 6.2.2. Example MAKESERVER Addstream The following example shows the MAKESERVER addstream generated by the MAS call in 6.2.1. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL @USE UC$PF,OTM$*TM$LIB @ASG,A UC$PF. @UC,SI,TLIB$.SREPTABLE/O,,,NO-DEBUG #include "xatmi.h" extern void COBSUB1(TPSVCINFO *); extern void COBSUB2(TPSVCINFO *); extern void COBSUB3(TPSVCINFO *); int hi_scode = 2; int svr_type = 1; /* UCOB server void (*tpservice[])(tpsvcinfo *) = { COBSUB1, COBSUB2, 7833 5080 009 6 9

Extended Mode Servers COBSUB3 }; @. *****END OF SREPTABLE***** @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT EXTENDED APNAME myserver OUTPUT FILE,TLIB$ VERSION,O @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$LIB,OTM$*TM$LIB @USE LOCAL$,TM$UTIL @USE AP$,MY*WORK @USE RTS$,SYS$LIB$*EMOMRTS @LINK,LE,TPF$.myserver INCLUDE TM$UTIL.SERVER$MAIN/O INCLUDE TLIB$.AP$NAME/O INCLUDE TLIB$.SREPTABLE/O INCLUDE LOCAL$.TPSVRINIT/O INCLUDE LOCAL$.TPSVRDONE/O INCLUDE AP$.SVC1 INCLUDE AP$.SVC2 INCLUDE AP$.SVC3 RESOLVE ALL REFERENCES USING TM$LIB, RTS$, LCN PROCESS FOR EXTENDED ZOOM 6 10 7833 5080 009

Extended Mode Servers DELETE ALL DEFINITIONS EXCEPT START$ @. *****END OF SERVER LINK***** Example 6 4. MAKESERVER Addstream for a COBOL TIP Server 6.2.3. Components of an Extended Mode TIP Server An extended mode TIP server has the following components. Table 6 2. Extended Mode TIP Server Components Component AP$NAME SERVER$MAIN Service routine SREPTABLE tpsvrdone() routine tpsvrinit() routine Description Contains the name of the server and a 63-word buffer used to interface with UDS. AP$NAME does not contain any code. This element is generated by the MAKEAP$NAME utility in the MAKESERVER addstream. Server main program for C and COBOL service routines. This component is stored in the TM$UTIL file. One or more user-written C Compiler or COBOL Compiler application programs. An array containing the entry point address of each service routine. The server main program uses the scode as an index into this table to find each service routine. The SREPTABLE is generated in the MAKESERVER addstream. Final processing routine called by the server main program just before termination. A default version is in the TM$UTIL file; you can substitute your own version. Initial processing routine called by the server main program at the start of execution. A default version is in the TM$UTIL file; you can substitute your own version. 6.3. Building an Extended Mode Batch Server To build an extended mode batch server, follow these steps: 1. Create a make-form for input to the MAS utility (see 5.1.2). 2. Call the MAS utility. Use the following options on the call to the MAS utility, depending on the programming language you are using: C language Use the C (C Compiler) and B (batch) options, for example @OTM$*TM$UTIL.MAS,CB my*infile.,my*outfile.,myserver 7833 5080 009 6 11

Extended Mode Servers COBOL language Use the U (COBOL Compiler) and B (batch) options, for example @OTM$*TM$UTIL.MAS,UB my*infile.,my*outfile.,myserver You can also include other options on the MAS utility call. See 5.1.3 for more information about the format and options of the MAS utility call. 3. (Optional) If your site has site-specific linking requirements, customize the MAKESERVER runstream accordingly. 4. Execute the MAKESERVER runstream produced by the MAS utility. The statement to execute MAKESERVER from a demand or batch run is @ADD MAKESERVER. If you execute MAKESERVER from a batch run, do the following: Be sure the batch run can access the MAKESERVER file. If you need to keep the output elements from MAKESERVER after the batch run completes, modify the MAKESERVER addstream to place those elements in cataloged files. 5. Create the runstream needed to start your batch server. You must have a runstream to start the server, whether you start the server with the TMBSD server dispatcher utility or manually (@START or @ADD). 6.3.1. Example MAS Call The following example creates an extended mode COBOL batch server. The service routine names conform to the naming rules for COBOL subprograms. The MAKESERVER addstream generated is shown in 6.3.2. @OTM$*TM$UTIL.MAS,BUN,,myserver *FILES AP MY*WORK *ROUTINES # SCODE SVC ROUTINE NAME LIBNO BANKNO ELT/VERSION # ----- ---------------- ----- ------ ----------- 0 COBSUB1 - - SVC1 1 COBSUB2 - - SVC2 2 COBSUB3 - - SVC3 # END OF MAKE-FORM @EOF OLTP-TM2200 3R1 -- Fri Mar 8 14:19:03 1996 *REMARK: Server execution environment is BATCH. *REMARK: Server language is UCOB. *REMARK: Addstream to build "myserver" is in file "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Example 6 5. MAS Input for a COBOL Batch Server 6 12 7833 5080 009

Extended Mode Servers 6.3.2. Example MAKESERVER Addstream The following example shows the MAKESERVER addstream generated by the MAS call in 5.3.1. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL @USE UC$PF,OTM$*TM$LIB @ASG,A UC$PF. @UC,SI,TLIB$.SREPTABLE/O,,,NO-DEBUG #include "xatmi.h" extern void COBSUB1(TPSVCINFO *); extern void COBSUB2(TPSVCINFO *); extern void COBSUB3(TPSVCINFO *); int hi_scode = 2; int svr_type = 1; /* UCOB server void (*tpservice[])(tpsvcinfo *) = { COBSUB1, COBSUB2, COBSUB3 }; @. *****END OF SREPTABLE***** @ADD TM$UTIL.MAKEAP$NAME 7833 5080 009 6 13

Extended Mode Servers ENVIRONMENT EXTENDED APNAME myserver OUTPUT FILE,TLIB$ VERSION,O @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$LIB,OTM$*TM$LIB @USE LOCAL$,TM$UTIL @USE AP$,MY*WORK @USE RTS$,SYS$LIB$*EMOMRTS @LINK,LE,TPF$.myserver INCLUDE TM$UTIL.SERVER$MAIN/O INCLUDE TLIB$.AP$NAME/O INCLUDE TLIB$.SREPTABLE/O INCLUDE LOCAL$.TPSVRINIT/O INCLUDE LOCAL$.TPSVRDONE/O INCLUDE AP$.SVC1 INCLUDE AP$.SVC2 INCLUDE AP$.SVC3 RESOLVE ALL REFERENCES USING TM$LIB, RTS$, LCN PROCESS FOR EXTENDED DELETE ALL DEFINITIONS EXCEPT START$ @. *****END OF SERVER LINK***** Example 6 6. MAKESERVER Addstream for a COBOL Batch Server 6 14 7833 5080 009

Extended Mode Servers 6.3.3. Components of an Extended Mode Batch Server An extended mode batch server has the following components. Table 6 3. Extended Mode Batch Server Components Component AP$NAME SERVER$MAIN Service routine SREPTABLE tpsvrdone() routine tpsvrinit() routine Description Contains the name of the server and a 63-word buffer used to interface with UDS. AP$NAME does not contain any code. This element is generated by the MAKEAP$NAME utility in the MAKESERVER addstream. Server main program for C and COBOL service routines. This component is stored in the TM$UTIL file. One or more user-written C Compiler or COBOL Compiler application programs. An array containing the entry point address of each service routine. The server main program uses the scode as an index into this table to find each service routine. The SREPTABLE is generated in the MAKESERVER addstream. Final processing routine invoked by the server main program just before termination. A default version is in the TM$UTIL file; you can substitute your own version. Initial processing routine invoked by the server main program at the start of execution. A default version is in the TM$UTIL file; you can substitute your own version. 7833 5080 009 6 15

Extended Mode Servers 6 16 7833 5080 009

Section 7 Basic Mode Servers This section provides additional information about basic mode servers for HVTIP, TIP, or batch mode execution: Listings of the components of different types of basic mode servers Examples of MAS MAKESERVER output to build different types of basic mode servers This section contains the following topics. Topic Description Reference Building a basic mode HVTIP server Building a basic mode TIP server Building a basic mode batch server Example of using the MAS utility; components of a basic mode HVTIP server Example of using the MAS utility; components of a basic mode TIP server Example of using the MAS utility; components of a basic mode batch server 7.1 7.2 7.3 More information about building and modifying servers is in the following sections: Procedures for using the MAS utility (see Section 5) Using your own initial and final processing routines to modify the execution of servers (see Section 8) 7.1. Building a Basic Mode HVTIP Server To build a basic mode HVTIP server, follow these steps: Note: For information about collecting basic mode HVTIP service routines, see Open Distributed Transaction Processing Programming Guide. 1. Create a make-form for input to the MAS utility (see 5.1.2). 2. Call the MAS utility. Use the A (ASCII COBOL Compiler) and V (HVTIP) options on the call to the MAS utility, for example @OTM$*TM$UTIL.MAS,AV my*infile.,my*outfile.,myserver You can also include other options on the MAS utility call. See 5.2.3 for more information about the format and options of the MAS utility call. 7833 5080 009 7 1

Basic Mode Servers 3. (Optional) If your site has site-specific collection requirements, customize the MAKESERVER runstream accordingly. In particular, if your site uses an installation of the ASCII COBOL Compiler that uses the FULL-LIB-CB, you need to remove the parameter UTILITY,NONE from the COBOL statement at the end of the MAKESERVER runstream. This allows the C$DML common bank to be mapped to your program. The C$DML common bank is required by the FULL-LIB-CB. 4. Execute the MAKESERVER runstream produced by the MAS utility. The statement to execute MAKESERVER from a demand or batch run is @ADD MAKESERVER. If you execute MAKESERVER from a batch run Be sure the batch run can access the MAKESERVER file. If you need to keep the output elements from MAKESERVER after the batch run completes, modify the MAKESERVER addstream to place those elements in cataloged files. 5. Create a VALTAB entry to register the HVTIP server. The M option in the VALTAB STATUS field is highly recommended for HVTIP server programs. Occasionally, the TIP system suspends scheduling of a transaction code to refresh internal data structures. Scheduling suspension stays in effect until currently executing programs terminate. An Open Distributed Transaction Processing HVTIP server program can execute indefinitely if you allow processing of multiple service requests with the MAX_TRANS and SVCTIMEOUT parameters in the Open Distributed Transaction Processing configuration. In this case, the scheduling suspension can cause some service requests to time out. The M option in VALTAB STATUS causes the TIP system to refresh the internal data structures without suspending scheduling. When a basic mode HVTIP server calls the Open Distributed Transaction Processing subsystem, it may need to perform a memory allocation request from URTS. Since basic mode transactions are not allowed to expand beyond their initial size, a memory allocation failure can occur. By default, a basic mode program is loaded with an extended mode stack bank of 4096 words. If messages are very large, this may not be enough. Event log messages, such as "unable to allocate activity local memory," can be displayed. You can increase the number of stack banks loaded with your program by increasing the VALTAB TCA value. The TCA value takes effect only when the Exec parameter TIPABSCALLSS is set to 2 or 3. 7 2 7833 5080 009

Basic Mode Servers The Exec parameter TIPABSCALLSS is set to either 2 or 3 to enable basic mode transactions to call an extended mode subsystem like Open Distributed Transaction Processing. TIPABSCALLSS allows extended mode stack banks, also known as heap banks or URTS$TABLES, to be loaded with the program for the Runtime System for Extended Mode Compilers (formerly, UCS Runtime System (URTS)) to use. The size of the bank loaded is determined by the TCA value. If TIPABSCALLSS is set to 3 and the N option is also set for the STATUS keyword on the VALTAB, the extended mode stack banks are allocated at initial program load time. If the N option is not set, the Exec and URTS allocate stack banks when the program first calls extended mode. This is less efficient than having TIP allocate the stack banks at initial program load time. The RUN keyword on the VALTAB entry contains the estimated standard units of processing (SUPs). If a TIP/HVTIP server is configured with a large MAXTRANS value, it is possible for the server to use the maximum number of SUPs allowed, resulting in a PCT overflow error. Set the value of MAXTRANS to stop this instance of the server before the maximum number of SUPs is used. The COP keyword on the VALTAB entry should be greater than or equal to the value of the CONCURRENCY parameter for the server in the *SERVERS section of the TMSCONFIG configuration file. If the value of the COP keyword is less than the value of CONCURRENCY, performance can be noticeably slower for the server when the CONCURRENCY value is reached. The REC keyword on the VALTAB entry can be used to specify options for MCB recoverable input messages. If your program will be configured with a group that has UDS specified as the resource manager and will be using MCB recoverable messages, be sure to verify that these settings are correct in your VALTAB entry. Open Distributed Transaction Processing will use the VALTAB settings during rollback processing if UDS is the resource manager. 6. Copy the absolute created by MAKESERVER into the appropriate HVTIP library file. 7.1.1. Example MAS Call The following example creates a basic mode ASCII COBOL HVTIP server. The MAKESERVER addstream generated is shown in 7.1.2. @OTM$*TM$UTIL.MAS,VAN,,myserver *PARAMETERS DBANKSIZE 4096 *FILES # TYPE NAME # -------- -------------------- ACOB SYS$LIB$*ACOB ACOBTIP SYS$LIB$*ACOB-TIPLIB XQT TPF$ *ROUTINES # SCODE SVC ROUTINE NAME LIBNO BANKNO # ----- ---------------- ----- ------ 0 SVCRTN1 23 4 7833 5080 009 7 3

Basic Mode Servers 1 SVCRTN2 24 6 2 SVCRTN3 25 8 # END OF MAKE-FORM @EOF OLTP-TM2200 3R1 -- Fri Mar 8 14:19:03 1996 *REMARK: Server execution environment is HVTIP. *REMARK: Server language is ACOB. *REMARK: Addstream to build "myserver" is in file MAKESERVER. END MAS. ERRORS: 0 WARNINGS: 0 Example 7 1. MAS Input for an ASCII COBOL HVTIP Server 7.1.2. Example MAKESERVER Addstream The following example shows the MAKESERVER addstream generated by the MAS call in 7.1.1. Explanations of the numbered lines follow the example. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL (1) @MASM,SI,TLIB$.SREPTABLE/R $ASCII $(0),C$BSREPTABLE* + 2. high scode 'SVCRTN1 '. scode 0 'SVCRTN2 '. scode 1 'SVCRTN3 '. scode 2 $END @. *****END OF SREPTABLE***** (2) @MASM,SE SYS$LIB$*ACOB.C$S333,TLIB$.C$S333-40 CREATE 'SVCRTN1' CREATE 'SVCRTN2' CREATE 'SVCRTN3' @. *****END OF C$S333***** (3) @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT BASIC APNAME myserver OUTPUT FILE,TLIB$ VERSION,R @EOF 7 4 7833 5080 009

Basic Mode Servers @EOF @. *****END OF AP$NAME ELEMENT***** (4) @ELT,I TLIB$.XFR$MNQ @. *****END OF EMPTY XFR$MNQ ELEMENT***** (5) @ELT,I TLIB$.CALL$MNQ SVCRTN1* $EQU 0270004000000. LIBNO=23, BANKNO=4 C$BSVCRTN1* $EQU 0 SVCRTN2* $EQU 0300006000000. LIBNO=24, BANKNO=6 C$BSVCRTN2* $EQU 0 SVCRTN3* $EQU 0310010000000. LIBNO=25, BANKNO=8 C$BSVCRTN3* $EQU 0 $END @. *****END OF CALL$MNQ ELEMENT***** @USE TM$ALIB,OTM$*TM$ALIB @USE LOCAL$,TM$UTIL @COPY,R TM$UTIL.NAME$ACCESS/R,TLIB$. @COPY,R TM$UTIL.SREPT$ACCESS/R,TLIB$. @COPY,R TM$UTIL.TPSS$ACCESS/R,TLIB$. @COPY,R TM$UTIL.CRM$ACCESS/R,TLIB$. @COPY,R TM$ALIB.CBEP$$TM,TLIB$. @COPY,R TM$ALIB.ACOB$PARAM/R,TLIB$. @COPY,R TM$ALIB.TX-ACOB/R,TLIB$. @PREP TLIB$. @. *****END OF MAKESERVER/START OF MAPHVTIP***** (6) @ADD SYS$LIB$*ACOB-TIPLIB.MAPHVTIP HVTIP ICP,myserver IN,SERVER$MAIN,R LOCAL TO,myserver FILE,TLIB$ ; MASM,SREPTABLE,R MASM,AP$NAME,R MASM,C$S333 LOCAL TO,myserver FILE,LOCAL$ ; COBOL,TPSVRINIT,R COBOL,TPSVRDONE,R REL TM$UTIL ABS TPF$ CONTROL TLIB$ IBANKS ARE STATIC 7833 5080 009 7 5

Basic Mode Servers DBANKADDRESS 0130000 DBANK IS 4096 OWN LIB,TLIB$ COBOL LIB,SYS$LIB$*ACOB TIPVERSION,SYS$LIB$*ACOB-TIPLIB ; NOCOMMON @EOF @EOF COMMON BANKED UTILITY,NONE Example 7 2. MAKESERVER Addstream for an ASCII COBOL HVTIP Server Explanation (1) @MASM,SI,TLIB$.SREPTABLE/R Creates the relocatable version of the SREPTABLE, which contains the entry point name of each service routine. (2) @MASM,SE SYS$LIB$*ACOB.C$S333,TLIB$.C$S333 Creates the relocatable version of the C$S333 table. This table is required by ASCII COBOL because the server main program uses the CALL identifier format of the CALL statement. The C$S333 table contains information needed by the compiler for calling the service routine. (3) @ADD TM$UTIL.MAKEAP$NAME Creates the AP$NAME element, which contains the name of the server and the Open Distributed Transaction Processing buffer for interfacing with UDS. (4) @ELT,I TLIB$.XFR$MNQ Creates the relocatable version of the XFR$MNQ element, which is referenced by the runstream generated by the MAPHVTIP skeleton see (6). The XFR$MNQ element is empty, because the server main program does not use XFR$ to transfer control to service routines. (5) @ELT,I TLIB$.CALL$MNQ Creates the relocatable version of the CALL$MNQ element, which is needed to transfer control to basic mode HVTIP subprograms (service routines). (6) @ADD SYS$LIB$*ACOB-TIPLIB.MAPHVTIP Calls the MAPHVTIP SSG skeleton provided by the ASCII COBOL HVTIP library. The MAPHVTIP skeleton generates an addstream that filters XFR$MNQ and CALL$MNQ, then maps the server. 7 6 7833 5080 009

Basic Mode Servers 7.1.3. Components of a Basic Mode HVTIP Server The following table describes the components of a basic mode HVTIP server. Table 7 1. Basic Mode HVTIP Server Components Component AP$NAME ASCII COBOLHVTIP library elements C$S333 CALL$MNQ CBEP$$TM CRM$ACCESS NAME$ACCESS SERVER$MAIN SERVER$MAINB SREPT$ACCESS SREPTABLE TPSS$ACCESS TPSVRDONE TPSVRDSYSDTA TPSVRINIT Description Contains the name of the server and a 63-word buffer used to interface with UDS. AP$NAME does not contain any code. AP$NAME is generated in the MAKESERVER addstream. ACOB-TIPLIB elements needed to resolve HVTIP references created by the ASCII COBOL Compiler. Defines an external reference for each service routine. It is required because the server main program invokes each service routine using the CALL identifier format of the CALL statement. The module name equate element that relates the entry point name of each HVTIP service routine to its library and bank number. The common bank entry point table for the Open Distributed Transaction Processing AFCB. Contains entry points called by the server main program to access Open Distributed Transaction Processing internal routines. Contains a function that the server main program calls to get the name of the server AP$NAME. Server main program for ASCII COBOL service routines. This component is in the TM$UTIL file. Server main program for ASCII COBOL service routines using COMMON-STORAGE. This component is in the TM$UTIL file. Contains a function that is called by the server main program to get the entry point name of a service routine from the SREPTABLE. The scode is used as an index into the SREPTABLE. A table of entry point addresses, one for each service routine. Contains entry points called by the server main program to access Open Distributed Transaction Processing internal routines. Final processing routine called by the server main program just before termination. A default version is the TM$UTIL file; you can substitute your own version. The data entry portion of TPSVRDONE that is generated by the ASCII COBOL Compiler. Initial processing routine called by the server main program at the start of execution. A default version is in the TM$UTIL file; you can substitute your own version. 7833 5080 009 7 7

Basic Mode Servers Table 7 1. Basic Mode HVTIP Server Components Component TPSVRISYSDTA XFR$MNQ Description The data portion of TPSVRINIT that is generated by the ASCII COBOL Compiler. Element created to meet the input requirement of the ACOB-TIPLIB.MAPHVTIP SSG skeleton. XFR$MNQ is empty because the server main program does not use XFR$ to call a service routine. 7.2. Building a Basic Mode TIP Server To build a basic mode TIP server, follow these steps: 1. Create a make-form for input to the MAS utility (see 5.1.2). 2. Call the MAS utility. Use the A (ASCII COBOL Compiler) and T (TIP) options on the call to the MAS utility. If the server is to be a reentrant program, also include the R option. For example @OTM$*TM$UTIL.MAS,ATR my*infile.,my*outfile.,myserver You can also include other options on the MAS utility call. See 5.1.3 for more information about the format and options of the MAS utility call. 3. (Optional) If your site has site-specific collection requirements, customize the MAKESERVER runstream accordingly. 4. Execute the MAKESERVER runstream produced by the MAS utility. The statement to execute MAKESERVER from a demand or a batch run is @ADD MAKESERVER. If you execute MAKESERVER from a batch run Be sure the batch run can access the MAKESERVER file. If you need to keep the output elements from MAKESERVER after the batch run completes, modify the MAKESERVER addstream to place those elements in cataloged files. 5. Create a VALTAB entry to register the TIP server. The M option in the VALTAB STATUS field is highly recommended for TIP server programs. Occasionally, the TIP system suspends scheduling of a transaction code to refresh internal data structures. Scheduling suspension stays in effect until currently executing programs terminate. An Open Distributed Transaction Processing TIP server program can execute indefinitely if you allow processing of multiple service requests with the MAX_TRANS and SVCTIMEOUT parameters in the Open Distributed Transaction Processing configuration. In this case, the scheduling suspension can cause some service requests to time out. The M option in VALTAB STATUS causes the TIP system to refresh the internal data structures without suspending scheduling. 7 8 7833 5080 009

Basic Mode Servers When a basic mode TIP server calls the OLTP subsystem, it may need to perform a memory allocation request from URTS. Since basic mode transactions are not allowed to expand beyond their initial size, a memory allocation failure can occur. By default, a basic mode program is loaded with an extended mode stack bank of 4096 words. If messages are very large, this may not be enough. Event log messages, such as " unable to allocate activity local memory, can be displayed. You can increase the number of stack banks loaded with your program by increasing the VALTAB TCA value. The TCA value takes effect only when the Exec parameter TIPABSCALLSS is set to 2 or 3. The Exec parameter TIPABSCALLSS is set to either 2 or 3 to enable basic mode transactions to call an extended mode subsystem like Open Distributed Transaction Processing. TIPABSCALLSS allows extended mode stack banks, also known as heap banks or URTS$TABLES, to be loaded with the program for the Runtime System for Extended Mode Compilers (formerly, UCS Runtime System (URTS)) to use. The size of the bank loaded is determined by the TCA value. If TIPABSCALLSS is set to 3 and the N option is also set for the STATUS keyword on the VALTAB, the extended mode stack banks are allocated at initial program load time. If the N option is not set, the Exec and URTS allocate stack banks when the program first calls extended mode. This is less efficient than having TIP allocate the stack banks at initial program load time. The RUN keyword on the VALTAB entry contains the estimated standard units of processing (SUPs). If a TIP/HVTIP server is configured with a large MAXTRANS value, it is possible for the server to use the maximum number of SUPs allowed, resulting in a PCT overflow error. Set the value of MAXTRANS to stop this instance of the server before the maximum number of SUPs is used. The COP keyword on the VALTAB entry should be greater than or equal to the value of the CONCURRENCY parameter for the server in the *SERVERS section of the TMSCONFIG configuration file. If the value of the COP keyword is less than the value of CONCURRENCY, performance can be noticeably slower for the server when the CONCURRENCY value is reached. The REC keyword on the VALTAB entry can be used to specify options for MCB recoverable input messages. If your program will be configured with a group that has UDS specified as the resource manager and will be using MCB recoverable messages, be sure to verify that these settings are correct in your VALTAB entry. Open Distributed Transaction Processing will use the VALTAB settings during rollback processing if UDS is the resource manager. 6. Copy the absolute produced by MAKESERVER into the appropriate standard TIP program file. 7833 5080 009 7 9

Basic Mode Servers 7.2.1. Example MAS Call The following example creates a basic mode ASCII COBOL TIP server. The MAKESERVER addstream generated is shown in 7.2.2. @OTM$*TM$UTIL.MAS,TRAN,,myserver *PARAMETERS MEMBLOCKS 10 TPSVRINIT MYSVRINIT/REL TPSVRDONE MYSVRDONE/REL *FILES # TYPE NAME # -------- -------------------- ACOB SYS$LIB$*ACOB ACOBTIP SYS$LIB$*ACOB-TIPLIB TIP TIP$*TIPLIB$ AP MY*WORKFILE LOCAL LOCAL*CODEFILE XQT TPF$ *ROUTINES # SCODE SVC ROUTINE NAME LIBNO BANKNO ELT/VERSION # ----- ---------------- ----- ------ ----------- 0 SVCRTN1 - - SVCRT1 1 SVCRTN2 - - SVCRT2 2 SVCRTN3 - - SVCRT3 # END OF MAKE-FORM @EOF OLTP-TM2200 3R1 -- Wed Mar 13 13:29:03 1996 *REMARK: Server execution environment is TIP. *REMARK: Server language is ACOB. *REMARK: Addstream to build "myserver" is in file "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Example 7 3. MAS Input for an ASCII COBOL TIP Server 7 10 7833 5080 009

Basic Mode Servers 7.2.2. Example MAKESERVER Addstream The following example shows the MAKESERVER addstream generated by the MAS call in 7.2.1. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL @MASM,SI,TLIB$.SREPTABLE/R $ASCII $(0),C$BSREPTABLE* + 2. high scode 'SVCRTN1 '. scode 0 'SVCRTN2 '. scode 1 'SVCRTN3 '. scode 2 $END @. *****END OF SREPTABLE***** @MASM,SE SYS$LIB$*ACOB.C$S333,TLIB$.C$S333-40 CREATE 'SVCRTN1' CREATE 'SVCRTN2' CREATE 'SVCRTN3' @. *****END OF C$S333***** @MASM,SI,TLIB$.C$SMC10 $(0),C$FIRST* C$LAST* $RES 5120. 10*512 $RES 1 7833 5080 009 7 11

Basic Mode Servers $END @. *****END OF C$SMCn***** @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT BASIC APNAME myserver OUTPUT FILE,TLIB$ VERSION,R @EOF @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$ALIB,OTM$*TM$ALIB @USE LOCAL$,LOCAL*CODEFILE @USE AP$,MY*WORKFILE @PREP TLIB$. @MAP,IS,TPF$.myserver NOT TPF$. LIB TLIB$(DBANK$/$EVEN). Must be LIB'd first. LIB (IBANK$/$ODD,DBANK$/$EVEN) LIB TM$ALIB() LIB SYS$LIB$*ACOB() LIB TIP$*TIPLIB$() IBANK,MC IBANK$,01000 IN TM$UTIL.SERVER$MAIN/R IN TM$UTIL.SREPT$ACCESS/R IN TM$UTIL.NAME$ACCESS/R IN TM$UTIL.TPSS$ACCESS/R IN TM$UTIL.CRM$ACCESS/R 7 12 7833 5080 009

Basic Mode Servers IN LOCAL$.MYSVRINIT/REL IN LOCAL$.MYSVRDONE/REL IN AP$.SVCRT1 IN AP$.SVCRT2 IN AP$.SVCRT3 DBANK,M DBANK$,0130000 IN TM$UTIL.SERVER$MAIN/R IN SYS$LIB$*ACOB-TIPLIB.C$S400/TIP IN LOCAL$.MYSVRISYSDTA/REL IN LOCAL$.MYSVRDSYSDTA/REL IN AP$.SVCRT1SYSDTA IN AP$.SVCRT2SYSDTA IN AP$.SVCRT3SYSDTA END @. *****END OF SERVER COLLECTION***** Example 7 4. MAKESERVER Addstream for an ASCII COBOL TIP Server 7.2.3. Components of a Basic Mode TIP Server The following table describes the components of a basic mode TIP server. Table 7 2. Basic Mode TIP Server Components Components AP$NAME ASCII COBOL TIP library elements C$S333 Description Contains the name of the server and a 63-word buffer used to interface with UDS. AP$NAME does not contain any code. AP$NAME is generated in the MAKESERVER addstream. ACOB-TIPLIB elements needed to resolve TIP references created by the ASCII COBOL Compiler. Defines an external reference for each service routine. It is required because the server main program invokes each service routine using the CALL identifier format of the CALL statement. 7833 5080 009 7 13

Basic Mode Servers Table 7 2. Basic Mode TIP Server Components Components C$SMCn CBEP$$TM CRM$ACCESS NAME$ACCESS SERVER$MAIN Service routine SREPT$ACCESS SREPTABLE TPSS$ACCESS TPSVRDONE TPSVRDSYSDTA TPSVRINIT TPSVRISYSDTA Description Reserves n 512-word blocks of memory for TIP servers. The common bank entry point table for the Open Distributed Transaction Processing AFCB. Contains entry points called by the server main program to access Open Distributed Transaction Processing internal routines. Contains a function that the server main program calls to get the name of the server AP$NAME. Server main program for ASCII COBOL service routines. This component is in the TM$UTIL file. One or more user-written ASCII COBOL subprograms. Contains a function that is called by the server main program to get the entry point name of a service routine from the SREPTABLE. The scode is used as an index into the SREPTABLE. A table of entry point addresses, one for each service routine. Contains entry points called by the server main program to access Open Distributed Transaction Processing internal routines. Final processing routine invoked by the server main program just before termination. A default version is the TM$UTIL file; you can substitute your own version. The data entry portion of TPSVRDONE that is generated by the ASCII COBOL Compiler. Initial processing routine called by the server main program at the start of execution. A default version is in the TM$UTIL file; you can substitute your own version. The data portion of TPSVRINIT that is generated by the ASCII COBOL Compiler. 7.3. Building a Basic Mode Batch Server To build a basic mode batch server, follow these steps: 1. Create a make-form for input to the MAS utility (see 5.1.2). 2. Call the MAS utility. Use the A (ASCII COBOL Compiler) and B (batch) options on the call to the MAS utility, for example @OTM$*TM$UTIL.MAS,AB my*infile.,my*outfile.,myserver You can also include other options on the MAS utility call. See 5.1.3 for more information about the format and options of the MAS utility call. 3. (Optional) If your site has site-specific collection requirements, customize the MAKESERVER runstream accordingly. 7 14 7833 5080 009

Basic Mode Servers 4. Execute the MAKESERVER runstream produced by the MAS utility. The statement to execute MAKESERVER from a demand or batch run is @ADD MAKESERVER. If you execute MAKESERVER from a batch run, do the following: Be sure the batch run can access the MAKESERVER file. If you need to keep the output elements from MAKESERVER after the batch run completes, modify the MAKESERVER addstream to place those elements in cataloged files. 5. Create the runstream needed to start your batch server. You must have a runstream to start the server, whether you start the server with the TMBSD server dispatcher utility or manually (@START or @ADD). 7.3.1. Example MAS Call The following example creates a basic mode ASCII COBOL batch server. The MAKESERVER addstream generated is shown in 6.3.2. @OTM$*TM$UTIL.MAS,BAN,,myserver *FILES # TYPE NAME # -------- -------------------- ACOB SYS$LIB$*ACOB AP TPF$ XQT TPF$ *ROUTINES # SCODE SVC ROUTINE NAME LIBNO BANKNO ELT/VERSION # ----- ---------------- ----- ------ ----------- 0 SVCRTN1 - - SVCRT1 1 SVCRTN2 - - SVCRT2 2 SVCRTN3 - - SVCRT3 # END OF MAKE-FORM @EOF OLTP-TM2200 3R1 -- Wed Mar 13 13:29:03 1996 *REMARK: Server execution environment is BATCH. *REMARK: Server language is ACOB. *REMARK: Addstream to build "myserver" is in file "MAKESERVER." END MAS. ERRORS: 0 WARNINGS: 0 Example 7 5. MAS Input for an ASCII COBOL Batch Server 7833 5080 009 7 15

Basic Mode Servers 7.3.2. Example MAKESERVER Addstream The following example shows the MAKESERVER addstream generated by the MAS call in 7.3.1. @FREE TLIB$. @ASG,T TLIB$.. Temporary library file. @USE TM$UTIL,OTM$*TM$UTIL @MASM,SI,TLIB$.SREPTABLE/R $ASCII $(0),C$BSREPTABLE* + 2. high scode 'SVCRTN1 '. scode 0 'SVCRTN2 '. scode 1 'SVCRTN3 '. scode 2 $END @. *****END OF SREPTABLE***** @MASM,SE SYS$LIB$*ACOB.C$S333,TLIB$.C$S333-40 CREATE 'SVCRTN1' CREATE 'SVCRTN2' CREATE 'SVCRTN3' @. *****END OF C$S333***** @ADD TM$UTIL.MAKEAP$NAME ENVIRONMENT BASIC APNAME myserver OUTPUT FILE,TLIB$ VERSION,R @EOF 7 16 7833 5080 009

Basic Mode Servers @EOF @. *****END OF AP$NAME ELEMENT***** @USE TM$ALIB,OTM$*TM$ALIB @USE LOCAL$,TM$UTIL @USE AP$,TPF$ @PREP TLIB$. @MAP,IS,TPF$.myserver NOT TPF$. LIB TLIB$(DBANK$/$EVEN). Must be LIB'd first. LIB (IBANK$/$ODD,DBANK$/$EVEN) LIB TM$ALIB() LIB SYS$LIB$*ACOB() LIB SYS$*RLIB$() IBANK,MR IBANK$,01000 IN TM$UTIL.SERVER$MAIN/R IN TM$UTIL.SREPT$ACCESS/R IN TM$UTIL.NAME$ACCESS/R IN TM$UTIL.TPSS$ACCESS/R IN TM$UTIL.CRM$ACCESS/R IN LOCAL$.TPSVRINIT/R IN LOCAL$.TPSVRDONE/R IN AP$.SVCRT1 IN AP$.SVCRT2 IN AP$.SVCRT3 DBANK,MC DBANK$,0130000 IN TM$UTIL.SERVER$MAIN/R 7833 5080 009 7 17

Basic Mode Servers IN LOCAL$.TPSVRISYSDTA/R IN LOCAL$.TPSVRDSYSDTA/R IN AP$.SVCRT1SYSDTA IN AP$.SVCRT2SYSDTA IN AP$.SVCRT3SYSDTA END @. *****END OF SERVER COLLECTION***** Example 7 6. MAKESERVER Addstream for an ASCII COBOL Batch Server 7.3.3. Components of a Basic Mode Batch Server The following table describes the components of a basic mode batch server. Table 7 3. Basic Mode Batch Server Components Components AP$NAME C$S333 CBEP$$TM CRM$ACCESS NAME$ACCESS SERVER$MAIN Service routine SREPT$ACCESS SREPTABLE TPSS$ACCESS Description Contains the name of the server and a 63-word buffer used to interface with UDS. AP$NAME does not contain any code. AP$NAME is generated within the MAKESERVER addstream. Defines an external reference for each service routine. It is required because the server main program invokes each service routine using the CALL identifier format of the CALL statement. The common bank entry point table for the Open Distributed Transaction Processing AFCB. Contains entry points called by the server main program to access Open Distributed Transaction Processing internal routines. Contains a function that the server main program calls to get the name of the server AP$NAME. Server main program for ASCII COBOL service routines. This component is in the TM$UTIL file. One or more user-written ASCII COBOL subprograms. Contains a function that is called by the server main program to get the entry point name of a service routine from the SREPTABLE. The scode is used as an index into the SREPTABLE. A table of entry point addresses, one for each service routine. Contains entry points called by the server main program to access Open Distributed Transaction Processing internal routines. 7 18 7833 5080 009

Basic Mode Servers Table 7 3. Basic Mode Batch Server Components Components TPSVRDONE TPSVRDSYSDTA TPSVRINIT TPSVRISYSDTA Description Final processing routine called by the server main program just before termination. A default version is the TM$UTIL file; you can substitute your own version. The data entry portion of TPSVRDONE that is generated by the ASCII COBOL Compiler. Initial processing routine called by the server main program at the start of execution. A default version is in the TM$UTIL file; you can substitute your own version. The data portion of TPSVRINIT that is generated by the ASCII COBOL Compiler. 7833 5080 009 7 19

Basic Mode Servers 7 20 7833 5080 009

Section 8 Using Local Code to Modify Servers This section describes how you can use your own code to modify the execution of the server main program. You cannot modify the code of the server main program. You can modify execution of a server by creating your own versions of two routines called by the server main program: tpsvrinit(): the initial processing routine, called once by the server before it begins execution tpsvrdone(): the final processing routine, called once by the server before it ends execution Different versions of these programs exist for extended mode and basic mode servers. This section contains the following topics. Topic Description Reference Modifying server execution What you can modify and why 8.1 C and Java servers COBOL servers ASCII COBOL servers tpsvrinit() and tpsvrdone() syntax and examples for extended mode servers tpsvrinit() and tpsvrdone() syntax and examples for extended mode servers TPSVRINIT and TPSVRDONE syntax and examples for basic mode servers 8.2 8.3 8.4 8.1. Modifying Server Execution You cannot modify the code of the server main program. However, you can modify the execution of a server by creating your own versions of the tpsvrinit initial processing routine, or the tpsvrdone final processing routine, or both. In addition, when you build a server using the MAS utility, you can link your own version of these functions. For additional information about using MAS, see Section 5. 7833 5080 009 8 1

Using Local Code to Modify Servers Open Distributed Transaction Processing places no restrictions on the contents of the tpsvrinit or tpsvrdone routines. Your own routines can contain code to perform the processing you require, such as Writing messages to the event log Acquiring resources needed by service routines Releasing resources used by service routines Calling TRINIT$$ and TERM$$, if the server is started by MCB Saving initial values of system parameters for use in calculating application program performance statistics Checking the time and enabling special services using tpadvertise() and tpunadvertise() Beginning and ending transactions using the TX and XATMI interfaces 8.2. C and Java Servers For extended mode servers, the C and Java versions of the server main program calls the tpsvrinit() and tpsvrdone() functions, which must be written in the C language. You can modify the execution of an extended mode server by creating your own version of either or both functions. 8.2.1. Modifying tpsvrinit() The server main program calls tpsvrinit() once before it begins execution or calls any services. The call to the tpsvrinit() function is as follows: int tpsvrinit(argc, argv) int argc; char **argv; where: argc is set to 1. argv[0] is the name of the server as contained in the tp_apname element of the AP$NAME element. If the APNAME_REPLACE feature is turned on, this is the name of the server that was scheduled rather than the tp_apname from the AP$NAME element built into the server. See the Open Distributed Transaction Processing Administration Guide Volume 1 for more information about the APNAME_REPLACE parameter in the TMS_SWITCHES section of the *RESOURCES section of the TMSCONFIG file. To terminate the server gracefully when an error occurs in the user-supplied tpsvrinit(), tpsvrinit() must return -1. If tpsvrinit() returns an error value, the server main program still calls tpsvrdone(). 8 2 7833 5080 009

Using Local Code to Modify Servers 8.2.2. tpsvrinit() Example The following example shows a tpsvrinit() function that calls the userlog() function to write a message to the event log. int tpsvrinit(argc,argv) int argc; char **argv; { (void)userlog("server %s started.\n", argv[0]); return(0); } 8.2.3. Modifying tpsvrdone() Example 8 1. tpsvrinit() Routine The server main program calls tpsvrdone() once before it ends execution. The call to the tpsvrdone() function is as follows: void tpsvrdone() The server main program calls tpsrvdone() even if the earlier call to tpsrvinit() returned an error value. 8.2.4. tpsvrdone() Example The following example shows a tpsvrdone() routine that writes a message to the system event log. void tpsvrdone(void) { (void)userlog("server terminated.\n"); return; } 8.3. COBOL Servers Example 8 2. tpsvrdone() Routine For extended mode servers, the COBOL version of the server main program can use either the default tpsvrinit() and tpsvrdone() functions written in the C (see 7.2) or COBOL language versions of these functions, as described in this subsection. You can modify the execution of an extended mode server by creating your own version of either or both functions. To use the COBOL language versions of these routines, you must include the Y option of the MAS utility (see 5.1.3). 7833 5080 009 8 3

Using Local Code to Modify Servers 8.3.1. TPSVRINIT Example The server main program calls the TPSVRINIT routine once before it begins execution or calls any services. The following example shows a TPSVRINIT routine that writes a message to the event log using the USERLOG_ function. IDENTIFICATION DIVISION. PROGRAM-ID. TPSVRINIT. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES. PRINTER IS PRINTER. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-ULOG1-LEN PIC 9(10) COMP. 01 WS-ULOG1 PIC X(40). LINKAGE SECTION. 01 TPSVRINT-STATUS PIC S9(10) USAGE BINARY. 01 TPSVRINT-PARAM PIC S9(10) USAGE BINARY. 01 TPSVRNAME PIC X(12) USAGE DISPLAY. PROCEDURE DIVISION USING TPSVRINT-STATUS, TPSVRINT-PARAM, TPSVRNAME. DUMMY-PARAGRAPH. MOVE 'The server is started ' TO WS-ULOG1. MOVE 23 TO WS-ULOG1-LEN. CALL "USERLOG_" USING ws-ulog1, ws-ulog1-len. MOVE 0 TO TPSVRINT-STATUS. RETURN-PARAGRAPH. EXIT. Example 8 3. TPSVRINIT Routine TPSVRINT-STATUS determines the status of the server. A value of -1 terminates the server gracefully when an error occurs in the user-supplied TPSVRINIT routine. The server main program still calls the TPSVRDONE routine if TPSVRINT-STATUS has a value of -1. TPSVRINT-PARAM is set to 1. TPSVRNAME is the name of the server in the tp_apname element of the AP$NAME element. If the APNAME_REPLACE feature is turned on, this is the name of the server that was scheduled rather than the tp_apname from the AP$NAME element built into the server. See the Open Distributed Transaction Processing Administration Guide Volume 1 for more information about the APNAME_REPLACE parameter in the TMS_SWITCHES section of the *RESOURCES section of the TMSCONFIG file. 8 4 7833 5080 009

Using Local Code to Modify Servers TPSVRDONE Example The server main program calls the TPSVRDONE routine once before it ends execution. The following example shows a TPSVRDONE routine that writes a message to the system event log. IDENTIFICATION DIVISION. PROGRAM-ID. TPSVRDONE. ENVIRONMENT DIVISION. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-ULOG1-LEN PIC 9(10) COMP. 01 WS-ULOG1 PIC X(40). PROCEDURE DIVISION. DUMMY-PARAGRAPH. MOVE '*************************************** ' TO WS-ULOG1. MOVE 40 TO WS-ULOG1-LEN. CALL "USERLOG_" USING ws-ulog1, ws-ulog1-len. RETURN-PARAGRAPH. EXIT. Example 8 4. TPSVRDONE Routine 8.4. ASCII COBOL Servers For basic mode (ASCII COBOL) servers, the server main program calls the TPSVRINIT and TPSVRDONE routines, which must be written in the ASCII COBOL language. You can modify the execution of a basic mode server by creating your own version of either or both routines. 8.4.1. Modifying TPSVRINIT The server main program calls TPSVRINIT once before it begins execution or calls any services. The call to the TPSVRINIT routine is as follows: CALL "TPSVRINIT" USING TPSVRNAME TPSVRINIT-STATUS-REC. The following example shows the default TPSVRINIT routine. IDENTIFICATION DIVISION. PROGRAM-ID. TPSVRINIT. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. UNIVAC-1100. OBJECT-COMPUTER. UNIVAC-1100 MEMORY SIZE IS 3 MODULES. DATA DIVISION. LINKAGE SECTION. 01 TPSVRNAME PIC X(12). 01 TPSVRINT-STATUS PIC H9(10). PROCEDURE DIVISION USING TPSVRNAME TPSVRINT-STATUS. DUMMY-PARAGRAPH. 7833 5080 009 8 5

Using Local Code to Modify Servers MOVE 0 TO TPSVRINT-STATUS. RETURN-PARAGRAPH. EXIT. 8.4.2. Modifying TPSVRDONE Example 8 5. Default TPSVRINIT Routine The server main program calls TPSVRDONE once before it ends execution. The call to the TPSVRDONE routine is as follows: CALL "TPSVRDONE". The following example shows the default TPSVRDONE routine. IDENTIFICATION DIVISION. PROGRAM-ID. TPSVRDONE. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. UNIVAC-1100. OBJECT-COMPUTER. UNIVAC-1100 MEMORY SIZE IS 3 MODULES. DATA DIVISION. PROCEDURE DIVISION. RETURN-PARAGRAPH. EXIT. Example 8 6. Default TPSVRDONE Routine 8 6 7833 5080 009

Section 9 Using the Security Service This section describes the Open Distributed Transaction Processing security service, which provides secured access to Open Distributed Transaction Processing server transactions from the Internet. For secured access, the Internet user provides security information to the security service. The service must pass authentication by the OS 2200 environment before that user is allowed to do any transaction work (end service requests) in the OS 2200 environment. The following terms are related to the security service. An end service is an Open Distributed Transaction Processing service that needs to be executed by an Internet user. It can be a new generation service or a Heritage Application Access (HAA) service. A security service is a C code module supplied by Unisys and written in the form of a standard Open Distributed Transaction Processing service. It processes user-id authentication requests and, if successful, calls an end service for that user. The owner can customize this code module to fit environmental needs. In the code and examples in this section, the security service is named secsvc. A security server is the result of building the security service into an Open Distributed Transaction Processing batch, TIP, or HVTIP server. When the security service is called by a tpconnect() function, the security server executes. In the examples, it is named secsvr. A Transaction Integrator security gateway is a specialized Transaction Integrator (formerly, WebTx) gateway that runs on a Windows NT or UnixWare Web server machine. This gateway is built as a client application to interoperate in conversation mode with the Open Distributed Transaction Processing security service. This code module can be customized to meet environmental needs. 7833 5080 009 9 1

Using the Security Service This section contains the following topics. Topic Description Reference Security service components Functional overview Security service processing Environment requirements OLTP configuration requirements Dependencies CALL SESSION$CTRL interface, OCMS activity, and template code overviews for the security service and Transaction Integrator security gateway Information flow and processing points among the Transaction Integrator security gateway, Open Distributed Transaction Processing security service, and Open Distributed Transaction Processing end service General security service processing, generic buffers, and new password processing The conditions regarding TIP, terminal security, CMS 1100 numbering, PIDs, TSF processor, SESSION$CTRL interface, and communications MAX_THREADS, user log, PID pool, and TD_CNV_TIME Throughput, passwords, and ELMS messages 9.1 9.2 9.3 9.4 9.5 9.6 Operations OCMS activity, TSF processor, and TD2200 9.7 Administration Building the security server, updating TMSCONFIG, building headers, installing VIEWs, and securing the user log file 9.8 Security service limitations Transaction Integrator considerations User accountability 9.9 SSL environment and operations 9.10 Customization considerations Database logging, session timeout optimization, non-web-based client development, end service programming, message logging, and disclaimer 9.11 Security service template code Source code for the security service 9.12 Security service VIEWs Source code for VIEWs secsvc_view and retmsg 9.13 Security service message header Source code for header file secmsgs.h 9.14 Message logging LLMS and ROQ return status messages from CALL SESSION$CTRL 9.15 9 2 7833 5080 009

Using the Security Service 9.1. Security Service Components The components of the Open Distributed Transaction Processing security service are described in the following subsections: SESSION$CTRL interface OCMS activity Session manager subsystem component Security service template code Transaction Integrator security gateway and HTML templates 9.1.1. Operating System SESSION$CTRL Interface The CALL SESSION$CTRL interface was released in System Base level 7R1 as a secured operating system interface; however, it is not enforced on fundamental level security systems. The interface can authenticate the following security information: user-id, password, new password, account, project, clearance level, and compartment set. Authenticate means to pass the OS 2200 sign-on requirements for the security level of your system. Using the CALL SESSION$CTRL interface to authenticate security information creates an open Transaction Processing (TIP) session. This session is immediately terminated and not used by Open Distributed Transaction Processing software. The interface is called only to verify that the user can pass the operating system sign-on checks. It means, however, that the user-ids of all callers must have access to the TIP environment. 9.1.2. The OCMS Activity The Open CMS (OCMS) activity is an Open Distributed Transaction Processing realtime activity that is started as a task under the transaction management system control (TMSC) run. The activity dequeues authentication requests placed on the subsystem request queue by a security server and calls the SESSION$CTRL interface to process the request. To call the interface, OCMS must register as an open CMS type and establish a routing output queue (ROQ) and a position identifier (PID) pool based on configuration information. The results for a processed authentication request are placed on the ROQ by the operating system. When authentication results are available, the OCMS activity removes the result from the ROQ and delivers the reply to the waiting security server. 9.1.3. Open Distributed Transaction Processing Session Manager Subsystem Component The session manager subsystem component provides the means for the security server and OCMS activity to communicate authentication requests and responses. 7833 5080 009 9 3

Using the Security Service 9.1.4. Open Distributed Transaction Processing Security Service Template Code The template code is a working Open Distributed Transaction Processing service written in the C language that processes authentication requests presented in the format of the input view, secsvc_view (refer to 9.13.1). Source code for the security service (refer to 9.12) is in element secsvc/c in the source file (file 10) on the release tape. The code module provides one method of processing authentication requests from the Internet user to secure the desired end service call. You can modify this code to suit your needs. The input and output VIEW buffers for the security service are defined in source element security/view. When entered into the VADD processor, these VIEWs produce the needed include headers retmsg.h and secsvc-view.h. The messages the security service uses for logging and returning information are defined in source element secmsgs/h. These elements are in the source file on the release tape. 9.1.5. Transaction Integrator Security Gateway and HTML Templates The Transaction Integrator security gateway is provided by Transaction Integrator software. Contact your Unisys support representative for more information. 9.2. Functional Overview Transaction Integrator software provides a security gateway to act as an Open Distributed Transaction Processing client that packages input from a Web page (coded in HTML) and establishes a conversational connection with the Open Distributed Transaction Processing security service. The security service authenticates the caller and calls the requested Open Distributed Transaction Processing end service. The security service is a Unisys provided code module in the form of a template. It is intended the customer can modify the security service to suit particular needs. The Transaction Integrator security gateway can operate in a Windows NT or UnixWare environment, using HTP/ic or Pathway to communicate with Open Distributed Transaction Processing software. 9 4 7833 5080 009

Using the Security Service The following figure is a functional overview of the security service. Explanations of the numbered steps follow the figure. PC Windows NT or UnixWare Web Browser Web Server Transaction Integrator DLLs HTML Pages 2 Transaction Integrator Gateways 3 HTP/ic or Pathway OS 2200 ClearPath IX Open DTP Software Transaction Security Service 4 Figure 9 1. Security Service Functional Overview The numbered steps identify the following information and processing flow in the figure: 1. A Web browser presents an HTML page that requests the following minimally required information from the user: user-id, password, and Open Distributed Transaction Processing end service information. You can customize the HTML page to embed or request other security information elements, such as a new password, account number, project-id, clearance level, and compartment set. 2. When the page is submitted, the Web server program passes the following information to the Transaction Integrator gateway: user-id, password, Open Distributed Transaction Processing end service information, Open Distributed Transaction Processing security service request, Open Distributed Transaction Processing end service name to call, end service input/output buffer types, and browser CGI variables. 3. The Transaction Integrator security gateway acts like an Open Distributed Transaction Processing client and packages the following information in an internally defined input buffer (secsvc_view): security information, CGI variables, and the Open Distributed Transaction Processing end service name to be called. 7833 5080 009 9 5

Using the Security Service The buffer is used on a send-only conversational connection (established by the tpconnect() function with the tpsendonly flag) to the Open Distributed Transaction Processing security service. The Transaction Integrator security gateway client passes any cookies associated with the Internet user, one at a time, using the tpsend() function. A maximum of 20 cookies and 20 tpsend() function calls are allowed. After the final cookie is sent, the gateway calls tpsend() with the tprecvonly flag set to pass control of the conversation to the security service. The Transaction Integrator security gateway client then waits for an authentication response to a tprecv() function call. If the authentication request is successful, Transaction Integrator software a. Allocates an end service input buffer (using the tpalloc() function) based on the previous HTML information. b. Fills in the user supplied data. c. Sends the end service input buffer (using the tpsend() function). d. Calls the tprecv() function to obtain the end service results. e. Forwards the end service results to the Web caller. The conversation ends. If the authentication request is unsuccessful, the Transaction Integrator security gateway displays an error page containing the error message buffer returned by the security service. The conversation ends. 4. When the security service is called as a result of the Transaction Integrator security gateway tpconnect() function, the service calls the Open Distributed Transaction Processing subsystem to enqueue the authentication request based on the security information provided. The security service waits until the OCMS activity processes the request using the SESSION$CTRL interface. If the authentication request is successful, the security service a. Sends a successful condition to the waiting Transaction Integrator security gateway client (using the tpsend() function). b. Calls the tprecv() function to obtain the end service input buffer. c. Calls the end service using the tpcall() function (after receiving the end service input buffer). d. Returns the end service results to the Transaction Integrator security gateway client using the tpreturn() function. The conversation ends. If the authentication request is unsuccessful, the security service returns a failure condition using the tpreturn() function and provides a message buffer indicating the error. The conversation ends. 9 6 7833 5080 009

Using the Security Service 9.3. Security Service Processing The general flow of security service processing is as follows: tprecv() /* loop on tprecv() function to obtain all cookies SESSENQ() /* call the subsystem gate to enqueue authentication request /* wait until a response is available if (authentication success) tpsend() /* return success to waiting gateway client tprecv() /* wait for end service input buffer tpcall() /* tpcall end service on behalf of secured Internet user tpreturn() /* return end service results and end conversation if (authentication error) log error tpreturn() /* return error message and end conversation 9.3.1. Using a Generic Buffer The security service can be a generic front-end authentication service to any end service without knowing the end service input or output buffer types. For the successful authentication case, the security service call to the tprecv() function to obtain the end service input buffer can use any generic buffer. When the tprecv() function is processed, the generic buffer is reallocated to match the actual end service input buffer type sent by the client. The security service passes the reallocated buffer to the end service using the tpcall() function. 9.3.2. Processing a New Password The security service is coded not to call the end service when the authentication results in the following message: Your password has been replaced. Although authentication is successful for this status, the Internet user is informed that a password change has taken place before proceeding. The security service returns the password replacement message and ends the conversation without calling the end service. The Internet user must back up to the original page of entry, reenter the password using the new password, and resubmit the page to execute the end service. You can alter this processing to call the end service, if you wish. 7833 5080 009 9 7

Using the Security Service 9.4. Environment Requirements The following environment conditions are required for the security service to work: TIP session control must be configured (a requirement of using the SESSION$CTRL interface for authentication). Terminal security must be configured (a requirement of using the SESSION$CTRL interface for authentication). Dynamic CMS numbering is used for the OCMS activity. The Exec automatically allocates the CMS number to the OCMS activity. Any user-id to be authenticated must have run mode TIP (a requirement of using the SESSION$CTRL interface for authentication). The subsystem owner must be given the SESSION$CTRL privileged interface (a requirement of using the SESSION$CTRL interface for authentication). Position identifiers (PID) are required. A range of PIDs is needed by the OCMS activity to process multiple concurrent authentication requests presented by multiple security servers. Provide a range in TMSCONFIG sufficient to cover your expected load of concurrent requests. Contact your site administrator for the PIDs you can use. The TSF processor is required if TIP or HVTIP servers are used. If the security server is a TIP or HVTIP transaction, it must be scheduled by the TIP scheduling facility (TSF) processor in an environment where TIP session control is configured. The SESSION$CTRL operating system feature is required and must be available on your system. Flexible Authentication must not be installed. Use OSI-TP or TD2200, depending on the environment, to handle communications to Open Distributed Transaction Processing software. The Transaction Integrator security gateway operates In the Windows NT environment using HTP/ic to HTP/x In the UnixWare environment using Pathway to TD2200 9 8 7833 5080 009

Using the Security Service 9.5. Open Distributed Transaction Processing Configuration Requirements The security service places configuration requirements on the following values: MAX_THREADS User log PID pool TD_CNV_TIME (UnixWare environment only) 9.5.1. MAX_THREADS Increase the value of the TMSCONFIG MAX_THREADS parameter by One (1). This is needed for the OCMS activity. The expected number of concurrent authentication requests. This matches the expected number of concurrent security servers. 9.5.2. User Log The security service is coded to record events and messages in a user log. Configure a user log in your TMSCONFIG file similar to the following example: 9.5.3. PID Pool *RESOURCES event_log; event_type = OLTP_USER; output_device = FILE; file_control = "otm$*userlog."; file_descriptor = "user"; event_queue_size = 2000 OCMS position identifier (PID) pool values must be entered in the SPECIAL_VALUES entry of the resources section of the TMSCONFIG configuration file. The starting PID and ending PID must be entered in the following form: OCMS_PID_POOL = "low:high" The values low and high must be integers greater than zero. The value for low must be less than or equal to the value for high. This is required only if OCMS is used. Its default value is 0:0. Obtain these values from your site administrator. 7833 5080 009 9 9

Using the Security Service 9.5.4. TD_CNV_TIME (UnixWare Environment Only) At initialization, the security gateway establishes a connection with TD2200 software for communications from the UnixWare environment through Pathway software. The security gateway performs tpconnect() function calls to the security service using this connection. The TD_CNV_TIME timeout value in the TMSCONFIG file controls the length in time for this connection. If the interval between user conversations (that is, transmissions of the HTML page to this gateway) could be longer than the TD_CNV_TIME value allows, the recommendation is to increase the value. The gateway attempts to reestablish the connection, but that involves repeating unnecessary work in restoring the timed out connection. If the connection times out, Open Distributed Transaction Processing software logs the following: TD conversation index # has exceeded configured conversation time of # minutes and is being timed out. 9.6. Dependencies The security service has dependencies on Throughput Passwords ELMS messages 9.6.1. Managing Throughput The security server processes one authentication request and one end service tpcall() function at a time. This implies that multiple concurrent authentication requests require multiple concurrent copies of the security server. It is recommended to take the default setting (no limit) for the concurrency parameter in the TMSCONFIG security server entry. Note: If only one Transaction Integrator security gateway client exists, only one authentication request is sent at any time. Internet user access is processed sequentially through that one instance of the gateway. However, multiple platforms (each with a Transaction Integrator security gateway) or up to 31 instances of a security gateway on a single platform can access the mainframe. Also, if the security gateway on a single platform is given different names, up to 31 instances can exist for each name. 9 10 7833 5080 009

Using the Security Service 9.6.2. Handling Passwords and New Passwords The security service always processes a new password that exists in the secsvc_view input buffer instead of calling the end service. When the user enters a new password, the security service returns the message "Your password has been replaced." The security service calls the desired end service only if the password is valid and not being changed. Therefore, if the OS 2200 configuration allows password changes within short periods of time, it is possible the end service is never called when a new password exists on each input. Since the HTML designer decides whether to allow the user to enter a new password on each screen, the design should handle password changes to coincide with security service processing. The following paragraphs recommend a processing algorithm. When the user transmits an HTML page containing end service information but no new password, the security service can return the following message: Your password has expired. If the password is expired, link the returned error page to a change-password page. Transmission of the change-password page should return the following message: Your password has been replaced. Once the password is replaced, the user can click the browser Back button to the initial page, update the password field, and transmit the page again. The security service now calls the desired end service. 9.6.3. ELMS Messages Important explanations for error statuses are in the documentation portion of Open Distributed Transaction Processing message numbers 48012 and 48028. Use the ELMS ehelp processor to read these explanations. Refer to the Open Distributed Transaction Processing Administration Guide Volume 1 for a description of ELMS messages and using the ehelp processor. 9.7. Operations Operation of the security service depends on the following software: OCMS activity TSF processor TD2200 (UnixWare environment only) 9.7.1. Open CMS (OCMS) Activity The OCMS activity must be running for the security service to function. This activity initializes the subsystem authentication request queue for the security service. The OCMS activity is started and terminated by the transaction management system control (TMSC) processor, using the UP OCMS and DN OCMS commands. 7833 5080 009 9 11

Using the Security Service 9.7.2. TSF Processor Because TIP session control must be configured, the TIP scheduling facility (TSF) processor, rather than TIP server dispatcher (TMTSD), is needed to schedule TIP or HVTIP security servers (or any other Open Distributed Transaction Processing server). 9.7.3. TD2200 (UnixWare Environment Only) The TD2200 component of the TMSC processor must be started before the Transaction Integrator security gateway is started in the UnixWare environment. 9.8. Administration Administration of the security service involves Building headers and installing VIEWs Building the security server Updating the TMSCONFIG file Securing the user log file 9.8.1. Building Headers and Installing VIEWs Call the VADD processor to Build the security service VIEW header files secsvc-view/h and retmsg/h Register the VIEWs in the Open Distributed Transaction Processing bank descriptor table (BDT) file @otm$*tm$run.vadd,uh input-source-file-name.security/view, output-header-file-name. 9.8.2. Building the Security Server To build the security server 1. Compile the service code. 2. Use the MAS utility to build the security service into an Open Distributed Transaction Processing batch, TIP, or HVTIP server. 3. Load the server into the appropriate execution file or library. 9 12 7833 5080 009

Using the Security Service 9.8.3. Updating the TMSCONFIG File A sample *SERVER TMSCONFIG entry for the security server as an HVTIP or TIP server can look like the following: *SERVERS secsvr trancode = "secsvr" ; ag_name = "appnin" ; ag_number = 9 ; maxtrans = 10 ; svctimeout = 30000 A sample *SERVICES TMSCONFIG entry for the security service can look like the following: *SERVICES secsvc name="secsvc" server = secsvr scode = 0 access= ON 9.8.4. Securing the User Log File Since the security service is coded to log processing input, results, and errors, it is recommended you secure the user log file by applying an access control record (ACR) to the file. For a TIP or HVTIP security server, restrict access to the user-id that starts the TSF processor. Because TSF schedules the security server, the server takes on the security attributes of this activity. For a batch mode security server, If you are not using the /U option on the @START image in the Open Distributed Transaction Processing TMSCONFIG file, restrict access to the user-id that started the TMSC run. Because the batch server dispatcher (TMBSD) is started by TMSC, batch servers run under the attributes of the TMSC user-id. If you are using the /U option on the @START image in the Open Distributed Transaction Processing TMSCONFIG file, restrict access to either The user-id on the @RUN image in the start file The user-id on the @START image Note: If you customize the security service to log to a database file rather than the user log, you can apply the same securing mechanisms to the alternate log file. Security Service Limitations 7833 5080 009 9 13

Using the Security Service Once the Open Distributed Transaction Processing security service authenticates the Internet user, the only accountability available for that user is through subsystem and security service logging. The Internet user end service transaction is not running under the user-id in secsvc_view. The Internet user transaction is running under one of the following: The user-id that started the TSF processor for TIP/HVTIP security servers The TMSC user-id for batch security servers An alternate user-id for batch security servers As a consequence, TIP file security and Exec logging occurs for the user-id associated with these processors, rather than the Internet user. 9.9. Transaction Integrator Considerations For added security, run Transaction Integrator software in a secure sockets layer (SSL) environment. For successful initialization of the security gateway in the UnixWare environment, the TD2200 component of the TMSC processor must be running. 9.10. Customization Considerations Consider the following issues when customizing the security service (discussed in the following subsections): Database logging Session timeout optimization Non-Internet-based client development End service programming Message logging Note: The following disclaimer applies to customized security services. This security service demonstrates one way to provide user authentication in an Open Distributed Transaction Processing system. If you encounter problems, submit problem reports in the usual way, specifying the keyword SECURITY. If you modify the security service in any way to accommodate a site-specific authentication mechanism and encounter problems, first reproduce the problem using an unmodified version of the security service before reporting the problem. 9.10.1. Database Logging You can revise all security service user log entries and write them to a database file using the logical data manager (LDM) of your choice. 9 14 7833 5080 009

Using the Security Service 9.10.2. Session Timeout Optimization As an optimization technique, you can add a timestamp function to the security service that records the time at initial sign-on with the other security information to a database file record for that user. The security service could compare this timestamp to a session timeout value known by the security service. For an incoming authentication request, search the database file for that user's record to find the initial sign-on time. If the time is in the range of the session timeout value, the security service can call the end service without enqueuing an authentication request to the subsystem. 9.10.3. Non-Internet-Based Client Development Although this security feature was developed for use with Web sites, you can develop a client to interface with the security service the same as the Transaction Integrator security gateway. This would allow locations other than Web sites to use the authentication functionality of the security service. 9.10.4. End Service Programming The security service can call an end service written in either the C or COBOL programming language. To accommodate COBOL end services, add the -s option to the argument field in the Transaction Integrator security gateway configuration. This option causes the gateway to fill the end service input buffer with spaces if needed by the COBOL end service. The security service needs no corresponding change. 9.10.5. Message Logging The statuses and messages in 9.15 are provided as a reference to help you understand security service processing and customize the template code. You can group them in whatever way supports your customized template. 9.11. Security Service Template Code This subsection contains the source code for the security service. Use the code as a template and modify it for your site if necessary. /* Copyright (c) 1998 Unisys Corporation. All rights reserved. UNISYS PROPRIETARY /********************************************************************** ******* /* /* The following code comprises the OLTP-TM2200 security service template. /* This service module can be built into an OLTP batch, TIP, or HVTIP server 7833 5080 009 9 15

Using the Security Service /* to request OS 2200 authentication of user security information which /* minimally consists of a user-id and a password. The security server will /* be invoked by a tpconnect call from the WebTx security gateway client. /* This module will call: /* /* tprecv() - receive in a loop all cookie buffers (up to 20) associated /* with the Web user /* SESSENQ() - an OLTP subsystem gate that enqueues an authentication request /* tpsend() - to return a successful authentication response to the gateway /* tprecv() - to obtain the end service input buffer from the gateway /* tpcall() - to call the desired end service /* tpreturn()- to return the end service results and end the gateway /* conversation /* /* If any of these calls fail, the security service will call tpreturn() with /* TPFAIL and end the conversation. /* /* Communication of information between the WebTx security gateway client /* and the security service is done by means of view 'secsvc_view' and /* view 'retmsg', both defined in source element security/view. This /* element contains the view definitions and must be input in to the VADD /* processor to produce the include headers "secsvc-view.h" and "retmsg.h". /* /* Communication of information between the security service and the OLTP /* authentication interface is done by means of the authinfo structure /* defined in the include header "session$mgr.h" or source element 9 16 7833 5080 009

Using the Security Service /* session$mgr/h. /* /* You may customize this code module to fit your needs. For example, calls /* to userlog() for recording events can be replaced by actual database /* writes to a secured file. /* Example 9 1. Security Service Template Code /* The released WebTx security gateway client currently ignores the rcode /* value (tpurcode) returned by tpreturn(), but it is available to the client /* for use if desired. The gateway client would have to be updated to use it. /* All status returns from the OS 2200 authentication interface are defined /* in the source element secmsgs/h and included here with "secmsgs.h". /* /********************************************************************** ******* #include <stdio.h> #include <stdlib.h> #include <string.h> #include <time.h> #include <xatmi.h> #include "retmsg.h" /* tpreturn buffer definition #include "otm-diag.h" /* defines userlog() call #include "secsvc-view.h" /* defines view needed for security check #include "session$mgr.h" /* defines SESSENQ() call and authinfo structure #include "secmsgs.h" /* authentication error messages #define TPFUNCTION_FAIL 100 #define AUTH_UNKNOWN 101 static long event = 0; void secsvc(svcinfo) TPSVCINFO *svcinfo; 7833 5080 009 9 17

Using the Security Service { int cstat, ret_type; int severity, aux_status, msg_id; /* session request reply stored here int cookie_cnt; /* cookie counter long olen, len, rlen; char *odata; /* output buffer for end service char *esvcbuf; /* input buffer for end service char *cookie_buf; /* buffer to hold incoming cookies struct retmsg *msgbuf; /* message buffer for return messages struct secsvc_view *security_buf; authinfo myauthinfo; /* passed in with session request security_buf = (struct secsvc_view *)svcinfo->data; rlen = sizeof(struct retmsg); /********************************************************************** ******* /* /* Recommendation: at this point record the contents of the incoming /* secsvc_view by making multiple userlog() calls or performing database /* writes to a secured file. Userlog() examples follow: /* /* userlog("secsvc: processing the following user security information:\n"); /* userlog("userid = %.*s\n",uidlen,security_buf->secsvc_userid); /* userlog("password = %.*s\n",pwdlen,security_buf->secsvc_passwd); /* userlog("new password = %.*s\n",pwdlen,security_buf- >secsvc_newpswd); /* userlog("account = %.*s\n",acctlen,security_buf->secsvc_account); /* userlog("project id = %.*s\n",projlen,security_buf- >secsvc_project); /* userlog("clearance = %.*s\n",clvlen,security_buf->secsvc_clevel); /* userlog("compartment = %.*s\n",cmptlen,security_buf- >secsvc_cmpset); /*. /*. 9 18 7833 5080 009

Using the Security Service /*. /* userlog("server name = %.*s\n",512,security_buf->server_name); /* /********************************************************************** ******* /********************************************************************** ******* /* /* Structure authinfo defines all the input parameters that can be used by /* OS 2200 authentication interface. The only required parameters are userid /* and password. Clear the local authinfo data structure with spaces. Space /* filling is required by the authentication interface. Then copy over any /* security parameters sent in from the secsvc_view. /* /********************************************************************** ******* memset(&myauthinfo, ' ', sizeof(struct authinfo)); memcpy(myauthinfo.userid, security_buf->secsvc_userid, UIDLEN); memcpy(myauthinfo.passwd, security_buf->secsvc_passwd, PWDLEN); memcpy(myauthinfo.newpswd,security_buf->secsvc_newpswd, PWDLEN); memcpy(myauthinfo.account,security_buf->secsvc_account, ACCTLEN); memcpy(myauthinfo.project,security_buf->secsvc_project, PROJLEN); memcpy(myauthinfo.clearance,security_buf->secsvc_clevel, CLVLEN); memcpy(myauthinfo.compartment,security_buf->secsvc_cmpset, CMPTLEN); /********************************************************************** ******* /* /* After secsvc_view information is obtained by the security service through /* the security gateway tpconnect() call, the security service will loop on /* the tprecv() call to obtain up to 20 cookies associated with the Web user. /* The cookie buffers are sent in as X_OCTET strings and can be recorded or /* used as needed. 7833 5080 009 9 19

Using the Security Service /* /* Note that in the example below, the cookies are logged using the userlog() /* function, which has a length limit of 260 bytes. However, the length /* standard for cookies is 4096 bytes. Therefore, the userlog() function will /* not print the entire contents of the cookie if it contains more than 260 /* characters. This can be solved by making multiple userlog calls for each /* cookie, or by using a different logging mechanism. /* /********************************************************************** ******* len = 1; cookie_buf = tpalloc("x_octet", NULL, len); if (cookie_buf == NULL) { userlog("secsvc: tpalloc for cookie buffer failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if cookie_cnt = 0; do { cstat = tprecv(svcinfo->cd,(char **)&cookie_buf,&len,tpnotime, &event); /* check cstat and event for successful return if (cstat == -1) { if (((tperrno == TPEEVENT) && (event!= TPEV_SENDONLY)) (tperrno!= TPEEVENT)) { msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg", rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for error message failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if memcpy(msgbuf->message,emsg_2,sizeof(emsg_2)); userlog("secsvc: tprecv failed.\n"); tpreturn(tpfail,tpfunction_fail,(char *)msgbuf,rlen,0); } /* end if /* if cookie was sent, log it in userlog } else if (cookie_buf!=null) { cookie_cnt++; userlog("secsvc: Cookie %d - %.*s\n", cookie_cnt, len, cookie_buf); 9 20 7833 5080 009

Using the Security Service memset(cookie_buf, '\0', len); } /* end if } while (event!= TPEV_SENDONLY); /********************************************************************** ******* /* /* Call the OLTP subsystem gate SESSENQ() to stage the authentication request. /* /* NOTE: /* Authentication is performed by the operating system SESSION$CTRL interface. /* The OLTP open cms activity, ocms, services the authentication request by /* dequeuing it from the subsystem queue and calling the interface on behalf /* of the server. Ocms must be up and running to process authentication /* requests. /* /* Provide the authentication information via the authinfo structure. The /* server will wait until the authentication request is complete. Processing /* status is initially determined by the return value 'cstat'. If this value /* is negative, processing of the authentication request was not attempted. /* This occurs for one of two reasons: the OLTP open cms activity, ocms, is /* not running or the session manager object failed to initialize. /* /* If 'cstat' is non-negative, processing of the authentication request was /* attempted. Processing status falls into 4 categories defined by the /* argument ret_type. These categories are defined in source element /* session$mgr/h to be: /* /* LLMS_TYPE - the call to SESSION$CTRL interface failed 7833 5080 009 9 21

Using the Security Service /* /* ROQ_TYPE - an operating system response to the SESSION$CTRL call was /* received which may or may not be successful /* /* PID_TYPE - all PIDs are in use (PIDs are required to call SESSION$CTRL) /* /* NO_OCMS_TYPE - the ocms activity is terminating for some reason /* /* A successful authentication return can only occur with the ROQ_TYPE. /* /* The arguments severity, msg_id, and aux_status are used for defining the /* result of an LLMS_TYPE or ROQ_TYPE return. PID_TYPE and NO_OCMS TYPE do /* not use these arguments. For LLMS_TYPE returns, severity is always 7 /* (fatal) and aux_status is not used; msg_id gives the cause. For a /* successful ROQ_TYPE return, all arguments will be 0. /* /* The values and interpretations for these arguments have been laid out in /* a functional specification produced by the SESSION$CTRL interface /* development group. They are listed in OLTP-TM2200 customer documentation. /* The statuses and messages the security service uses are documented in /* source element secmsgs/h. /* /********************************************************************** ******* cstat = SESSENQ(&myauthinfo, &ret_type, &severity, &msg_id, &aux_status); if (cstat < 0) { userlog("secsvc: OCMS activity is not running\n"); 9 22 7833 5080 009

Using the Security Service len = sizeof(struct retmsg); msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg",rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for error message failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,no_ocms_type,(char *)msgbuf,rlen,0); } /* end if /********************************************************************** ******* /* /* Check for successful authentication from SESSENQ (ret_type = ROQ_TYPE and /* msg_id = 0). If the request was successful, check for a password change /* (severity = 2). In the case of a password change, the end service is not /* called so that the user can be notified of the password change. Return the /* password change information and stop the service. /* /* Otherwise, get the end service information from the gateway and pass it /* into the tpcall(). Then return the success or failure of the end service to /* the client. /* /* ROQ_TYPE returns with severity = 3 are non-fatal and not checked here. /* However, they may be checked, and messages may be returned. Refer to /* OLTP-TM2200 customer documentation for explanations on these statuses. /* Refer to OLTP-TM2200 customer documentation for a table of all statuses /* and their meaning. /* /* Severities of 2 and 3 are still successful authentications. This means /* that the end service may still be called. However, it is impossible to /* both return a status message AND call the end service. If a message is 7833 5080 009 9 23

Using the Security Service /* returned to announce a password change, for example, the Web user must /* retry the request using the new password. /* /********************************************************************** ******* if ((ret_type == ROQ_TYPE) && (msg_id == 0)) { if ((severity == 2) && (aux_status == 020073)) { msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg",rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for authorization information failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if userlog("secsvc: password has been changed for userid %.*s.\n", UIDLEN, myauthinfo.userid); memcpy(msgbuf->message,emsg_020073,sizeof(emsg_020073)); tpreturn(tpsuccess,roq_type,(char *)msgbuf,rlen,0); } /* end if /********************************************************************** ******* /* /* Successful authentication /* Do any logging and continue toward the end service call. /* For example: /* userlog("secsvc: Authentication successful for userid %.*s.\n", /* UIDLEN, myauthinfo.userid); /* /********************************************************************** ******* /********************************************************************** ******* /* /* Tpsend() control of the conversation back to the gateway as an indication /* of successful authentication. /* /********************************************************************** 9 24 7833 5080 009

Using the Security Service ******* cstat = tpsend(svcinfo->cd,null,0,tprecvonly,&event); if (cstat == -1) { msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg",rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for error message failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if memcpy(msgbuf->message,emsg_2,sizeof(emsg_2)); userlog("secsvc: tpsend returned with tperrno %d.\n",tperrno); tpreturn(tpfail,tpfunction_fail,(char *)msgbuf,rlen,0); } /* end if /********************************************************************** ******* /* /* We need to get the information that will be passed to the end service from /* the gateway. To do this, send a tprecv() using a dummy buffer. This dummy /* buffer will be reallocated within the call to the actual type of buffer /* needed by the end service. This automatic reallocation is what allows the /* security service to be used as a generic front end to any end service /* which requires authentication. /* /********************************************************************** ******* len = 1; esvcbuf = tpalloc("x_octet", NULL, len); if (esvcbuf == NULL) { userlog("secsvc: tprecv tpalloc failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if /********************************************************************** ******* /* /* Call tprecv() to get end service information from the gateway. /* /********************************************************************** 7833 5080 009 9 25

Using the Security Service ******* cstat = tprecv(svcinfo->cd,(char **)&esvcbuf,&len,tpnotime,&event); /* check cstat and event for successful return if (cstat == -1) { if ((tperrno == TPEEVENT) && (event == TPEV_SENDONLY)) { /************************************************ /* /* Option to log status of tprecv() here. /* /************************************************ } else { msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg",rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for error message failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if memcpy(msgbuf->message,emsg_2,sizeof(emsg_2)); userlog("secsvc: tprecv failed.\n"); tpreturn(tpfail,tpfunction_fail,(char *)msgbuf,rlen,0); } /* end if } /* end if /********************************************************************** ******* /* /* Do a tpalloc() of the output buffer for the tpcall. This buffer is also /* automatically reallocated within the tpcall. This automatic reallocation /* is what allows the security service to be used as a generic front end to /* any end service which requires authentication. /* /********************************************************************** ******* olen = 1; odata = tpalloc("x_octet",null,olen); if (odata == NULL) { userlog("secsvc: tpalloc for end service output failed.\n"); tpfree((char *)esvcbuf); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if /********************************************************************** 9 26 7833 5080 009

Using the Security Service ******* /* /* Do tpcall() of end service. /* /********************************************************************** ******* cstat = tpcall(security_buf->endsvc,(char *)esvcbuf,len,&odata,&olen,0); if (cstat < 0) { userlog("secsvc: tpcall fail, tperrno = %d.\n",tperrno); tpfree(odata); tpfree((char *)esvcbuf); msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg",rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for error message failed.\n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if memcpy(msgbuf->message,emsg_2,sizeof(emsg_2)); tpreturn(tpfail,tpfunction_fail,(char *)msgbuf,rlen,0); } /* end if tpfree((char *)esvcbuf); /********************************************************************** ******* /* /* Call tpreturn() with TPSUCCESS and end service information. /* /********************************************************************** ******* tpreturn(tpsuccess,0,odata,olen,0); } /* end if /********************************************************************** ******* /* /* Authentication Failures from SESSENQ /* All other returns from SESSENQ are errors so tpalloc() a buffer, /* fill it with the appropriate error message, and tpreturn() TPFAIL. /* 7833 5080 009 9 27

Using the Security Service /********************************************************************** ******* msgbuf = (struct retmsg *)tpalloc("x_c_type","retmsg",rlen); if (msgbuf == NULL) { userlog("secsvc: tpalloc for error message failed. \n"); tpreturn(tpfail,tpfunction_fail,null,0,0); } /* end if switch (ret_type) { case LLMS_TYPE: /* LLMS error return if (msg_id < 0300) { /* System error userlog("secsvc: System related error from SESSION$CTRL call:" "0%o. See event log.\n", msg_id); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); } else { /* Bad data was passed to SESSION$CTRL CALL switch (msg_id) { case 0300: userlog("secsvc: Invalid character in userid: %.*s\n", UIDLEN, myauthinfo.userid); memcpy(msgbuf- >message,emsg_0300,sizeof(emsg_0300)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; case 0301: userlog("secsvc: Invalid character in password or new " "password. password: %.*s, new password: %.*s\n", PWDLEN, myauthinfo.passwd, PWDLEN, myauthinfo.newpswd); memcpy(msgbuf- >message,emsg_0301,sizeof(emsg_0301)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; case 0302: userlog("secsvc: Invalid character in clearance level:\ %.*s\n", CLVLEN, myauthinfo.clearance); memcpy(msgbuf- >message,emsg_0302,sizeof(emsg_0302)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; case 0303: userlog("secsvc: Invalid character in account number: \ %.*s\n", ACCTLEN, myauthinfo.account); 9 28 7833 5080 009

Using the Security Service memcpy(msgbuf->message,emsg_0303,sizeof(emsg_0303)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; case 0304: userlog("secsvc: Invalid character in project id: %.*s\n", PROJLEN, myauthinfo.project); memcpy(msgbuf->message,emsg_0304,sizeof(emsg_0304)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; case 0305: userlog("secsvc: Invalid character in compartment set:\ %.*s\n", CMPTLEN, myauthinfo.compartment); memcpy(msgbuf->message,emsg_0305,sizeof(emsg_0305)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; default: /* unknown error userlog("secsvc: unknown LLMS_TYPE msg_id 0%o\n",msg_id); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,llms_type,(char *)msgbuf,rlen,0); break; } /* end switch } /* end if break; case ROQ_TYPE: /* ROQ error return /* severity = 7 switch (aux_status) { case 0: if (msg_id == 2) { userlog("secsvc: Invalid userid/password entered\n"); memcpy(msgbuf->message,emsg_02,sizeof(emsg_02)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; } else { /* msg_id == 3 userlog("secsvc: %s\n", emsg_1); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; } /* end if case 020473: userlog("secsvc: %s\n", emsg_020473); memcpy(msgbuf- >message,emsg_020473,sizeof(emsg_020473)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 020573: userlog("secsvc: %s\n", emsg_020573); memcpy(msgbuf- >message,emsg_020573,sizeof(emsg_020573)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); 7833 5080 009 9 29

Using the Security Service break; case 020673: userlog("secsvc: %s\n", emsg_020673); memcpy(msgbuf- >message,emsg_020673,sizeof(emsg_020673)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 020773: userlog("secsvc: %s\n", emsg_020773); memcpy(msgbuf- >message,emsg_020773,sizeof(emsg_020773)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 021273: userlog("secsvc: %s\n", emsg_021273); memcpy(msgbuf- >message,emsg_021273,sizeof(emsg_021273)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 021373: userlog("secsvc: %s\n", emsg_021373); memcpy(msgbuf- >message,emsg_021373,sizeof(emsg_021373)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 021473: userlog("secsvc: %s\n", emsg_021473); memcpy(msgbuf- >message,emsg_021473,sizeof(emsg_021473)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 021573: userlog("secsvc: %s\n", emsg_021573); memcpy(msgbuf- >message,emsg_021573,sizeof(emsg_021573)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 021673: userlog("secsvc: %s\n", emsg_021673); memcpy(msgbuf- >message,emsg_021673,sizeof(emsg_021673)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 021773: userlog("secsvc: %s\n", emsg_021773); memcpy(msgbuf- >message,emsg_021773,sizeof(emsg_021773)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 022073: userlog("secsvc: %s\n", emsg_022073); 9 30 7833 5080 009

Using the Security Service memcpy(msgbuf- >message,emsg_022073,sizeof(emsg_022073)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 022173: userlog("secsvc: %s\n", emsg_022173); memcpy(msgbuf- >message,emsg_022173,sizeof(emsg_022173)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 022273: userlog("secsvc: %s\n", emsg_022273); memcpy(msgbuf- >message,emsg_022273,sizeof(emsg_022273)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 022373: userlog("secsvc: %s\n", emsg_022373); memcpy(msgbuf- >message,emsg_022373,sizeof(emsg_022373)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; case 022473: userlog("secsvc: %s\n", emsg_022473); memcpy(msgbuf- >message,emsg_022473,sizeof(emsg_022473)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; default: /* system failure userlog("secsvc: ROQ_TYPE system failure status: 0%o\n", aux_status); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,roq_type,(char *)msgbuf,rlen,0); break; } /* end switch break; case PID_TYPE: /* No PIDS available userlog("secsvc: No pids available in OCMS\n"); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,pid_type,(char *)msgbuf,rlen,0); break; case NO_OCMS_TYPE: /* OCMS is not up userlog("secsvc: OCMS activity terminated\n"); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,no_ocms_type,(char *)msgbuf,rlen,0); break;example 9 1. Security Service Template Code (cont.) 7833 5080 009 9 31

Using the Security Service default: userlog("secsvc: SESSENQ ret_type unknown: %d\n",ret_type); memcpy(msgbuf->message,emsg_1,sizeof(emsg_1)); tpreturn(tpfail,auth_unknown,(char *)msgbuf,rlen,0); break; } /* end switch } /* end secsvc Example 9 1. Security Service Template Code 9.12. Security Service VIEWs The VIEW definitions in this subsection are in source element security/view. Provide element security/view as input to the VADD processor to Create the security service header files Install the definitions in the Open Distributed Transaction Processing subsystem and bank descriptor table (BDT) file 9.12.1. VIEW secsvc_view VIEW secsvc_view (see the following code) is the initial Transaction Integrator security gateway VIEW for the tpconnect() function. It has the following basic parts: User security information For this release, the Transaction Integrator security gateway client minimally always fills in the first two security fields, user-id and password, for an initial end service request. Optional fields are available for the customer to use with a personalized version of the security gateway. An optional security field does not need to be completed with data. All security fields (first section in the VIEW) are defined to be ASCII characters with the sizes shown. The gateway client fills unused characters with spaces. Environment information The Transaction Integrator security gateway client fills in all available environment variables. End service name The Transaction Integrator security gateway client fills in the end service name from the action field in the HTML page. VIEW secsvc_view #type cname fbname count flag size null #---------------------------------------------------- # user security information used by SESSION$CTRL: carray secsvc_userid - 1-12 - (required) carray secsvc_passwd - 1-20 - (required) carray secsvc_newpswd - 1-20 - (optional) carray secsvc_account - 1-12 - (optional) 9 32 7833 5080 009

Using the Security Service carray secsvc_project - 1-12 - (optional) carray secsvc_clevel - 1-16 - (optional) carray secsvc_cmpset - 1-64 - (optional) # end service name to call if authentication succeeds: carray endsvc - 1-12 - (required) # environment information: carray Server_Software - 1-512 - carray Server_Name - 1-512 - carray Server_Protocol - 1-512 - carray Server_Port - 1-12 - carray Secure_Port - 1-12 - carray Request_Method - 1-12 - carray Path_Info - 1-512 - carray Path_Translated - 1-512 - carray Script_Name - 1-512 - carray Query_String - 1-1024 - carray Remote_Host - 1-512 - carray Remote_Addr - 1-512 - carray Auth_Type - 1-512 - carray Auth_Userid_Passwrd - 1-512 - carray Remote_User - 1-512 - carray Remote_Ident - 1-512 - carray Content_Type - 1-512 - carray Content_Length - 1-512 - carray Http_Accept - 1-512 - carray Http_User_Agent - 1-512 - carray InternalData - 1-512 - END 9.12.2. VIEW retmsg Example 9 2. VIEW secsvc_view The security service uses VIEW retmsg (see the following code) to send response messages to the gateway client on a tpreturn() function call. VIEW retmsg #type cname fbname count flag size null #----------------------------------------- # tpreturn message buffer carray message - 1-256 - END Example 9 3. View retmsg 7833 5080 009 9 33

Using the Security Service Security Service Message Header The security service uses the message header file secmsgs.h, as in the following code. /********************************************************************** ******* /* Copyright (c) 1998 Unisys Corporation. /* All rights reserved. /* UNISYS PROPRIETARY /********************************************************************** ******* #ifndef SECMSGS_H #define SECMSGS_H /********************************************************************** ******* /* NOTE! /* -------------------------------------------------------------------- ------- /* The following messages are used by the OLTP-TM2200 security service. /* Please refer to OLTP-TM2200 Administration Guide, Volume 2, for a complete /* table of statuses and messages returned by the authentication interface. /********************************************************************** ******* /********************************************************************** ******* /********************************************************************** ******* /********************************************************************** ******* /* SPECIAL USE MESSAGES /* Emsg_1 is a generic return message indicating a system-related failure has /* occurred. Either the OLTP event log or the security service userlog() will /* contain a description of the actual point of error. This message is used /* by the security service to make an entry in the userlog for the following: /* 9 34 7833 5080 009

Using the Security Service /* SESSENQ() call failure (cstat < 0) (detail in event log) /* LLMS_TYPE ret_type system failures (values < 0300) (detail in event log) /* default (unknown) cases in service switch constructs /* PID_TYPE ret_type (out of PIDs) (detail in event log) /* NO_OCMS_TYPE ret_type (detail in event log) /* ROQ_TYPE ret_type: (detail in event log) /* severity 7, msg_id 3, aux_status 0 /* severity 7, msg_id 1, aux_status 021073 /* severity 7, msg_id 1, aux_status 021173 /* severity 7, msg_id 1, aux_status 022573 /* severity 7, msg_id 1, aux_status 022673 /* severity 7, msg_id 1, aux_status 022773 /* /* Detailed descriptions of the system-related errors found in the event log /* are entered by OCMS activity code or the session manager object code. /* /********************************************************************** ******* Example 9 4. Security Service Message Header static char emsg_1[line_len] = {"Authentication failed due to a system failure. See OLTP-TM2200 logs.\n"}; static char emsg_2[line_len] = {"A processing error occurred. See OLTP-TM2200 logs.\n"}; /********************************************************************** ******* /* LLMS_TYPE ERROR MESSAGES /* If the ret_type argument from a security service SESSENQ() authentication /* request is LLMS_TYPE, this signifies the request was NOT processed and the 7833 5080 009 9 35

Using the Security Service /* call to SESSION$CTRL itself failed. The returned severity argument is /* always 7 (fatal), and the msg_id argument identifies the problem below. /* /* NOTE: msg_id values under 0300 are not mentioned here. These are system- /* related errors not caused or repaired by the Web user. They are logged /* by the OCMS activity in SESSrply() to the event log, and force OCMS to /* terminate. The security service can record the msg_id value if so desired. /* /********************************************************************** *** static char emsg_0300[line_len] = {"Userid has an illegal character: i.e. a character that is not\ alphanumeric, period, or dash.\n"}; static char emsg_0301[line_len] = {"Password has an illegal character: i.e. a space, a comma, or a slash.\n"}; static char emsg_0302[line_len] = {"Clearance level has an illegal character: i.e. not alphanumeric,\ dash, or dollar sign.\n"}; static char emsg_0303[line_len] = {"Account number has an illegal character: i.e. not alphanumeric,\ dash, or period.\n"}; static char emsg_0304[line_len] = {"Project-id has an illegal character: i.e. not alphanumeric, dash,\ or dollar sign.\n"}; static char emsg_0305[line_len] = {"Compartment Set has an illegal character: i.e. not alphanumeric,\ dash, or dollar sign.\n"}; /********************************************************************** ******* /* ROQ_TYPE SUCCESS MESSAGES /* The security service has been coded not to call the end service when a /* password gets replaced but instead to return this status. This is done to /* inform the Web user that their password has changed. The Web user 9 36 7833 5080 009

Using the Security Service must /* resubmit the end service request using the new password. /* /********************************************************************** ******* static char emsg_020073[line_len] = {"Your password has been replaced.\n"}; /********************************************************************** ******* /* ROQ_TYPE ERROR MESSAGES /* If the ret_type argument from a security service SESSENQ() authentication /* request is ROQ_TYPE and severity is 7 (fatal), the authentication request /* was processed but failed. The specific error is based on the aux_status /* argument. The following error messages were deemed helpful to return to /* the caller. Any system-related ROQ_TYPE error is recorded in the userlog /* and generic emsg_1 is returned instead (see SPECIAL USE MESSAGES above). /* These errors are not deemed fatal; OCMS continues to operate. /* /********************************************************************** ******* static char emsg_02[line_len] = {"An invalid user-id/password or ticket was entered.\n"}; static char emsg_020473[line_len] = {"You may not change your password yet.\n"}; static char emsg_020573[line_len] = {"Your password has not been replaced.\n"}; static char emsg_020673[line_len] = {"Your password has expired. You must change your password.\n"}; static char emsg_020773[line_len] = {"Your user-id will be disabled if you do not change your password.\n"}; static char emsg_021273[line_len] = {"Your new password contains invalid characters.\n"}; 7833 5080 009 9 37

Using the Security Service static char emsg_021373[line_len] = {"Your new password is too long.\n"}; static char emsg_021473[line_len] = {"Your new password is too short.\n"}; static char emsg_021573[line_len] = {"Your new password must be different than your old password.\n"}; static char emsg_021673[line_len] = {"Your new password must be different than your user-id.\n"}; static char emsg_021773[line_len] = {"You do not have access to the requested account number.\n"}; static char emsg_022073[line_len] = {"Your user-id is disabled. Contact your Site Administrator.\n"}; static char emsg_022173[line_len] = {"Your user-id has no access to TIP.\n"}; static char emsg_022273[line_len] = {"Your clearance level is not valid.\n"}; static char emsg_022373[line_len] = {"Your compartment set is not valid.\n"}; static char emsg_022473[line_len] = {"Your project-id is not valid.\n"}; #endif 9.13. Message Logging Security service processing produces informational messages and error messages. Various events during component initialization and authentication processing can trigger these messages. The OCMS activity can log the messages in the event log or the security service can log the messages in the user log and possibly send them to the Internet user. System-related, operating system, or internal Open Distributed Transaction Processing errors are collected as a group of messages the OCMS activity logs. Some of these errors can cause the OCMS activity to terminate. The details of these errors are not sent to the Internet user. Instead, the security service sends a generic system error message (emsg_1 or emsg_2 in secmsgs/h) to the gateway client, advising the user to look in the Open Distributed Transaction Processing event log or user log for details. If an error is a problem the user can correct or a key informational event the user should know about, the security service logs the message and sends it to the gateway client for display. 9 38 7833 5080 009

Using the Security Service The tables in 9.15.1 and 9.15.2 show all possible return statuses from the following key processing points: The OCMS SESSION$CTRL CALL The attempt by the OCMS activity to call the SESSION$CTRL interface can return the LLMS statuses in the tables in 9.15.1. The operating system result after processing that call If the call succeeds, the operating system places the authentication results on a routing output queue (ROQ). These statuses are identified in the tables in 9.15.2 as SESSION$CTRL ROQ return statuses. Customization Consideration These statuses and messages are provided as a reference to help you understand security service processing and customize the template code. You can group them in whatever way supports your customized template. 9.13.1. LLMS Return Status The LLMS return statuses are grouped as system errors and illegal characters in the following tables. The tables contain comments on how the security service handles them. For system errors (refer to the following table), OCMS logs the errors in the event log and terminates. The security service submits a user log indicating a system-related error occurred and uses tpreturn() to return a failure status to the security gateway client with the generic system error message (emsg_1). The conversation ends. Table 9 1. LLMS System Error Returns Severity Message-id Explanation 7 01 Packet version-id is not legal. 7 02 A reserved field is not zero. 7 03 TIP session control is not configured. 7 04 Terminal Security (TSS) is not configured. 7 05 Caller is not a registered CMS open type. 7 06 Illegal function requested in packet. 7 07 Maximum Open TIP sessions reached. 7 010 PID already has an open session. 7 011 PID is not assigned to your program. 7 012 ROQ request not found. 7 013 Session-id is not a valid id. 7 014 Session-id not in a valid state. 7833 5080 009 9 39

Using the Security Service 7 015 Caller is not connected to TIP. 7 016 Local session-id cannot be terminated; only remote sessions may be terminated. 7 020 Caller does not have the SSTOKEN privilege. 7 021 Caller did not provide the required sign-on information buffer in parameter 2 of the CALL. 7 022 Caller cannot create a local, open session because it is a transaction without a valid, traditional session. 7 023 System resource is not available to create an open session. 7 025 Open session control is not initialized. This can occur for all functions if an Open CMS statement is not registered before the CALL. 7 026 Illegal subfunction. 7 027 A problem occurred handling the sign-on information buffer specified in parameter 2 of the CALL statement. For errors involving illegal characters (refer to the following table), the security service submits a user log indicating the problem and recording the field that caused the problem. The security service uses tpreturn() to return a failure status to the security gateway client with a message containing the corresponding explanation. The conversation ends. Table 9 2. LLMS Illegal Character Returns Severity Message-id Explanation 7 0300 User-id has an illegal character: a space or a character that is not alphanumeric, period (.), or dash (-). 7 0301 Password has an illegal character: a space, comma (,) or slash (/). 7 0302 Clearance level has an illegal character: not alphanumeric, dash (-), or dollar-sign ($). 7 0303 Account number has an illegal character: not alphanumeric, dash (-), or period (.). 7 0304 Project-id has an illegal character: not alphanumeric, dash (-), or dollar-sign ($). 7 0305 Compartment set has an illegal character: not alphanumeric, dash (-), or dollar-sign ($). 9 40 7833 5080 009

Using the Security Service 9.13.2. SESSION$CTRL ROQ Return Status The tables in this subsection list the statuses from the routing output queue (ROQ) for processed SESSION$CTRL calls. The call itself was successful. The statuses indicate whether the authentication was successful, as follows: Severity 0 is a successful authentication. Severities 2 and 3 are successful authentications but contain informational messages that can be sent back to the Internet user or just ignored. Severity 7 indicates authentication failure of one of two types: User-related failure System-related failure For success status returns (refer to the following table), the OCMS activity does nothing with the statuses except pass them to the security service. For auxiliary status 020073, the security service submits an informational user log and uses tpreturn() to return the password replacement message without calling the end service. Both the OCMS activity and the security service ignore auxiliary statuses 020173, 020273, 020373. (You can change the security service to check for these statuses.) The security service proceeds with the tprecv() call to obtain the end service input buffer for the eventual tpcall() function. Table 9 3. ROQ Success Status Returns Severity Message-id Auxiliary Status Explanation 0 0 0 Successful authentication. 2 0 020073 Your password is replaced. 3 0 020173 Your current password expires tomorrow. 3 0 020273 Unable to process the passive profile; contact your site administrator. 3 0 020373 One or more environment variables in the passive profile were truncated. 7833 5080 009 9 41

Using the Security Service For user-related failures (refer to the following table), OCMS does nothing with the statuses except pass them to the security service. The security service submits a user log with the user-related error message and uses tpreturn() to return a failure status to the security gateway client with a message containing the corresponding explanation. The conversation ends. Table 9 4. ROQ User-Related Failure Status Returns Severity Message-id Auxiliary Status Explanation 7 2 0 An invalid user-id/password or ticket was entered. 7 1 020473 You may not change your password yet. 7 1 020573 Your password has not been replaced. 7 1 020673 Your password has expired. You must change your password. 7 1 020773 Your user-id will be disabled if you do not change your password. 7 2 021273 Your password contains invalid characters. 7 1 021373 Your password is too long. 7 1 021473 Your new password is too short. 7 1 021573 Your new password must be different than your old password. 7 1 021673 Your new password must be different than your user-id. 7 1 or 4 021773 You do not have access to the requested account number. 7 1 022073 Your user-id is disabled. Contact your site administrator 7 1 022173 Your user-id has no access to TIP. 7 1 or 4 022273 Your clearance level is not valid. 7 1 or 4 022373 Your compartment set is not valid. 7 1 or 4 022473 Your project-id is not valid. 9 42 7833 5080 009

Using the Security Service For system-related failures (refer to the following table), the OCMS activity logs these statuses in the event log and continues processing. The security service submits a user log with the generic system error message and uses tpreturn() to return a failure status with the generic system error message. The conversation ends. Table 9 5. ROQ System Failure Status Returns Severity Message-id Auxiliary Status Explanation 7 1 021073 Password processing is not available. You cannot sign on. 7 1 021173 Password processing cannot complete your password request. 7 1 022573 Your session has been terminated due to unavailable system resources. 7 1 022673 The Authentication and Session Initiation subsystem (ASIS) is not available to process the ticket. 7 1 022773 The Authentication and Session Initiation subsystem (ASIS) could not complete the ticket authentication because dialog with the user is required. 7 1 0 A system error occurred, preventing the session from opening. 7833 5080 009 9 43

Using the Security Service 9 44 7833 5080 009

Appendix A Restrictions, Operational Considerations, and Compatibility Restrictions are temporary limitations for a software product. Restrictions will be removed in a later release of the product. Operational considerations are permanent limitations on using a product. Compatibility concerns how Open Distributed Transaction Processing level 6R1 behaves with other products or system software or with previous releases of Open Distributed Transaction Processing software (formerly, OLTP-TM2200 and Open/OLTP). A.1. Restrictions The following restrictions apply to OS 2200 Open Distributed Transaction Processing level 6R1: Two-phase commit protocol is not supported in Partitioned applications environments Number of resource managers (RM) Only one RM can be associated with each logical Open Distributed Transaction Processing group defined in the configuration (*GROUPS section of the TMSCONFIG file). Because a given application program is associated with a single group, it can access only one local RM. Note: This restriction does not limit the number of RMs that can participate in a global transaction because the application program can request services from application programs associated with other logical Open Distributed Transaction Processing groups (or residing on remote systems). 7833 5080 009 A 1

Restrictions, Operational Considerations, and Compatibility A.2. Operational Considerations The following operational considerations apply to using Open Distributed Transaction Processing: A.2.1. Unsupported TX Calls The following calls defined in the X/Open TX specification are not supported: tx_set_commit_return (C and Java) TXSETCOMMITRET (COBOL and ASCII COBOL) setcommitreturn (JVM on OS 2200) The functions are in the TX library but return TX_NOT_SUPPORTED when called. A.2.2. COMP-5 Usage The COMP-5 usage specification feature, specified by the Open Group TX and XATMI application program interfaces (API), is not available for programs written in the ASCII COBOL Compiler. A.2.3. Advertising Services Advertising and unadvertising services are currently not supported for the JVM on OS 2200. A.3. Compatibility with Other Products or System Software The following subsections contain compatibility issues for Open Distributed Transaction Processing with other products or system software. A.3.1. Compatibility with Runtime System for Extended Mode Compilers If you are using a Runtime System for Extended Mode Compilers (formerly, URTS) level prior to 10R1B, to do a COMUS build of Open Distributed Transaction Processing, you must apply the workaround found in PLE 17514733. A.3.2. Compatibility with Unisys OS 2200 OSI-TP High- Performance Transaction Processing for XATMI (HTP/x) Open Distributed Transaction Processing is now compatible with User Authentication Level security available in HTP/x Level 7R1. A 2 7833 5080 009

Restrictions, Operational Considerations, and Compatibility A.3.3. Compatibility with Open Distributed Transaction Processing Level 4R1 The following compatibility issue applies to using Open Distributed Transaction Processing level 6R1 only if you have previously used level 4R1: In all levels lower than Open Distributed Transaction Processing level 6R1, the Two-Phase Commit (OLTP-2PC) and Heritage Application Access (OLTP-HAA) features are separately installed products. With level 6R1, these features are included in Open Distributed Transaction Processing. Separate installation of feature tapes for these products is no longer needed. Compatibility with Open Distributed Transaction Processing Level 5R1 There are no known compatibility issues for Open Distributed Transaction Processing level 5R1. A.3.4. Compatibility with Open Distributed Transaction Processing Level 8R1 The following compatibility issue applies to using Open Distributed Transaction Processing level 8R1 only if you have used a lower level. Previously, when starting a TIP server with an incorrect AP$NAME built in, the server printed the following warning message and continued processing: OTM030104: Problem matching server *1* with scheduled server name. Since the APNAME_REPLACE feature has been added in level 8R1, this message has changed to an error message and the server is terminated. If you want your servers to use a name other than the AP$NAME they were built with, you must turn on the APNAME_REPLACE configuration flag. See the Open Distributed Transaction Processing Administration Guide Volume 1 for more information about configuring application programs and using the APNAME_REPLACE configuration parameter. A.3.5. Compatibility with Open Distributed Transaction Processing level 9R1 The following compatibility issues apply to using Open Distributed Transaction Processing level 9R1 only if you have used a lower level. Note: Depending on your previous level of Open Distributed Transaction Processing, you may also need to look at the compatibility section for levels 7R1 and 8R1. Previously, if an application program configured with a group that named UDS as its resource manager issued a TXROLLBACK, Open Distributed Transaction Processing automatically determined the recovery (REC) options used during rollback processing rather than relying on the REC options from the VALTAB. 7833 5080 009 A 3

Restrictions, Operational Considerations, and Compatibility In some cases, this caused MCB recoverable input messages to be lost after a rollback because they would not get sent to the system error program (SEP). The Open Distributed Transaction Processing rollback code has been modified for the 9R1 level to default to the REC options specified on the VALTAB. Depending on the REC options specified, this allows recoverable input messages to be sent to the SEP. Please verify all REC options for transaction programs configured with UDS as the resource manager. The line following the processor call for Open Distributed Transaction Processing utility programs now includes the date and time of product generation. The following updates have been made to the TMSCON processor. Refer to Section 6 of the Open Distributed Transaction Processing Administration Guide Volume 1 for more information about these changes. A new mode called UPDATE has been added to the TMSCON processor. With the addition of this new mode, the rules for APPEND mode have changed. In particular, the rules for entering parameters in the *RESOURCES section have changed. The RMID field in the *GROUPS entry can no longer be changed with an APPEND mode TMSCONFIG. Remove the TDH_CLASS1 parameter from your TMSCONFIG if it is still specified. The obsolete TDH_CLASS1 parameter is no longer accepted in the TD2200 section of the TMSCONFIG. An error will now be printed if this parameter is entered. Previously a message was printed stating that the tag was no longer needed if the parameter was entered. There are several changes to minimum, maximum, and default values for TMSCONFIG parameters as follows o EVENT_QUEUE_SIZE minimum changed from 1 to 20 o TRACE_QUEUE_SIZE minimum changed from 1 to 20 o MAX_MSGQTIME default changed from 0 to 10 o MAX_REGTIME default changed from 60 to 5 o MAX_CLIENTS default changed from 0 to 10 o MAX_CONCUR_REQS maximum value no longer has to be less than 4200 o TDH_TOTAL default changed from 1 to 5 o CONCURRENCY (*SERVERS section) default changed from MAXINT to 5 A 4 7833 5080 009

Appendix B Thread-Control Commands Open Distributed Transaction Processing supports proprietary interfaces to allow Universal Data System (UDS) databases and File Control Superstructure (FCSS) files to participate in distributed transactions. B.1. OS 2200 Universal Data System (UDS) Open Distributed Transaction Processing supports a proprietary interface with Universal Database Control that allows UDS databases to participate fully in distributed transactions. The proprietary interface consists of the existing Universal Database Control (formerly, UDS Control) TCL ICR interface with these enhancements: It allows the transaction manager to indicate that the transaction semantics for the calling thread are under the control of the transaction manager rather than the application program. It accepts a PREPARE command, which secures database modifications made by the thread and places the ACTIVE step in the READY state. B.2. File Control Superstructure (FCSS) Open Distributed Transaction Processing supports a proprietary interface with the Exec that allows FCSS to participate fully in distributed transactions. The proprietary interface consists of the existing FCSS interface with these enhancements: It allows the transaction manager to indicate that the transaction semantics for the calling thread are under the control of the transaction manager rather than the application program. It accepts a PREPARE command, which secures database modifications made by the thread and places the ACTIVE step in the READY state. 7833 5080 009 B 1

Thread-Control Commands B.3. XA and Universal Database Control Functions The following table maps The Open Group XA functions to Universal Database Control functions. Table B 1. Mapping of XA Functions to Universal Database Control Functions XA Function Name xa_close xa_commit xa_end xa_open xa_prepare Universal Database Control Function Name Not applicable commit_thread, followed by end_thread** Not applicable Not applicable prepare_thread*, followed by end_thread if marked read-only** xa_recover recover_thread * omit_thread (for READY steps that are not ready in the transaction manager) xa_rollback omit_thread, followed by end_thread** xa_start begin_thread * This Universal Database Control function is supported only for Open Distributed Transaction Processing access. **end_thread is executed if transaction chaining is not in effect. You include UDS databases in the Open Distributed Transaction Processing environment by specifying optional parameters in the TMSCONFIG configuration file. There is no need to rebuild Open Distributed Transaction Processing. For information about the TMSCONFIG file, see the Open Distributed Transaction Processing Administration Guide Volume 1. B 2 7833 5080 009

Thread-Control Commands B.4. TX and Step Control The following table maps TX functions to step control actions. The righthand columns (FCSS and UDS) identify the RM for which the thread is configured. Table B 2. Mapping of TX Functions to Step Control Actions for RMs Thread Type FCSS UDS Client Non-HAA TIP/HVTIP server and service Batch server tx_open(): connects thread to TIP if not already connected. tx_begin(): starts a TIP two-phase commit step. Client can access TIP database. Client cannot access UDS database. Client can use the XATMI interface routines to call a server that is configured with UDS, FCSS, or MCB to be a part of the global transaction. tx_commit() or tx_rollback(): most cases, ends the two-phase commit step for all databases in the global transaction with the action specified. If transaction chaining is on, a tx_commit() performs a step advance, rather than a step terminate. If another global transaction is desired, a tx_begin() function must be performed to create a new two-phase commit step. This is followed by calls to the XATMI interface routines and, eventually, to the tx_commit() or tx_rollback() action. tx_close(): no step action. Client disconnects from TIP on termination. Same as client thread. Same as client thread. tx_open(): no step action. tx_begin(): starts a UDS two-phase commit step. Client can access TIP database, but must explicitly use the CONECT function to connect to TIP. This connection can occur anytime before accessing the TIP file. The TIP access is controlled by the UDS two-phase commit step. Client can access UDS database. Client can use the XATMI interface routines to call a server that is configured with UDS, FCSS, or MCB to be part of this global transaction. tx_commit() or tx_rollback(): ends the two-phase commit step for all databases in the global transaction with the action specified. If another global transaction is desired, a tx_begin() function must be performed to create a new two-phase commit step. This is followed by calls to the XATMI interface routines and, eventually, to the tx_commit() or tx_rollback() action. A connection to TIP is not necessary again since it was done previously, unless the client thread performed an explicit DISCON function. tx_close(): no step action. Client disconnects from TIP on termination. Same as client thread, but connection to TIP is not necessary. Same as client thread. 7833 5080 009 B 3

Thread-Control Commands B.5. Step Control for Nonglobal Transactions For nonglobal transactions, all threads (client, non-haa TIP/HVTIP server and service, and batch server) do not use TX functions. The client must use standard OS 2200 step control mechanisms to manage database updates. The client must perform the CONECT and DISCON functions, if accessing TIP files. The client can use the XATMI interface routines to call a server configured with UDS, FCSS, or MCB. The service must use standard OS 2200 step control mechanisms to manage database updates. B 4 7833 5080 009

Appendix C Java Package Contents The Java package com.unisys.os2200.tmapi contains the following class definitions that pertain to the View2java utility: The TransactionTP class which contains the inner class definition for TransactionTP.Buffer The TransactionView interface class This appendix describes the following topics. Topic Description Reference TransactionTP class Class definitions including the TransactionTP.Buffer class C.1 TransactionView interface class Class definition C.2 C.1. TransactionTP Contents The following is the skeleton of the public members of the TransactionTP class: /* * TransactionTP.java 1.00 00/07/25 package com.unisys.os2200.tmapi; import java.io.*; import java.lang.reflect.*; import java.util.*; public class TransactionTP 7833 5080 009 C 1

Java Package Contents { /* Flag bits for XATMI methods public static final int TPNOBLOCK = 0x00000001; public static final int TPSIGRSTRT = 0x00000002; public static final int TPNOREPLY = 0x00000004; public static final int TPNOTRAN = 0x00000008; public static final int TPTRAN = 0x00000010; public static final int TPNOTIME = 0x00000020; public static final int TPGETANY = 0x00000080; public static final int TPNOCHANGE = 0x00000100; public static final int TPCONV = 0x00000400; public static final int TPSENDONLY = 0x00000800; public static final int TPRECVONLY = 0x00001000; /* Service return values for rval public static final int TPFAIL = 0x20000000; public static final int TPSUCCESS = 0x04000000; /* XATMI methods public static int acall(string service, TransactionTP.Buffer buffer, long bufferlength) throws TPException; public static int acall(string service, TransactionTP.Buffer buffer, long bufferlength, long flags) throws TPException; C 2 7833 5080 009

Java Package Contents public static Buffer allocate(string type, String subtype, long length) throws TPException; public static void call(string service, TransactionTP.Buffer input, output, long bufferlength, TransactionTP.Buffer long flags) throws TPException; public static void cancel(int handle) throws TPException; public static int connect(string service, TransactionTP.Buffer buffer, long bufferlength, long flags) throws TPException; public static void disconnect(int handle) throws TPException; public static void free(transactiontp.buffer buffer); public static void getreply(int handle, TransactionTP.Buffer buffer) throws TPException; public static void getreply(int handle, TransactionTP.Buffer buffer, long flags) throws TPException; public static long gettpurcode(); public static Buffer reallocate(transactiontp.buffer buffer, long length) throws TPException; public static void receive(int handle, TransactionTP.Buffer buffer) 7833 5080 009 C 3

Java Package Contents throws TPException; public static void receive(int handle, TransactionTP.Buffer buffer, long flags) throws TPException; public static void send(int handle, TransactionTP.Buffer buffer, long bufferlength) throws TPException; public static void send(int handle, TransactionTP.Buffer buffer, long bufferlength, long flags) throws TPException; public static void returnresults(int rval, long rcode, TransactionTP.Buffer buffer, long bufferlength); public static void returnresults(int rval, long rcode, TransactionTP.Buffer buffer, long bufferlength, long flags); public static long types(transactiontp.buffer buffer, StringBuffer type, StringBuffer subtype) throws TPException; /* * Inner class TransactionTP.Buffer * This is the data buffer passed by XATMI methods public class Buffer { C 4 7833 5080 009

Java Package Contents public Thread thread; /* * Methods for getting and setting data buffer information public Buffer(long virtualaddress, int length); public byte getbyte(int offset); public byte[] getbyte(int offset, int size); public char getchar(int offset); public char[] getchar(int offset, int size); public char[][] getchar(int offset, int size, int count); public double getdouble(int offset); public double[] getdouble(int offset, int size); public float getfloat(int offset); public float[] getfloat(int offset, int size); public int getint(int offset); public int[] getint(int offset, int size); public boolean getisbufferupdated(); public long getlong(int offset); public long[] getlong(int offset, int size); public long getlonglong(int offset); public long[] getlonglong(int offset, int size); public short getshort(int offset); public short[] getshort(int offset, int size); public String getstring(int offset, int length); public String[] getstring(int offset, int length, int size); 7833 5080 009 C 5

Java Package Contents public int length(); public void setbyte(int offset, byte value); public void setbyte(int offset, byte[] value); public void setbytes(byte value); public void setchar(int offset, char value); public void setchar(int offset, char[] value); public void setchar(int offset, char[][] value, int size); public void setdouble(int offset, double value); public void setdouble(int offset, double[] value); public void setfloat(int offset, float value); public void setfloat(int offset, float[] value); public void setint(int offset, int value); public void setint(int offset, int[] value); public void setlong(int offset, long value); public void setlong(int offset, long[] value); public void setlonglong(int offset, long value); public void setlonglong(int offset, long[] value); public void setshort(int offset, short value); public void setshort(int offset, short[] value); public void setstring(int offset, String value, int length); public void setstring(int offset, String[] value, int length); public String tostring(); } // End inner class TransactionTP.Buffer /* * Methods for printing data buffer information C 6 7833 5080 009

Java Package Contents public static String tostring(char[] array); public static String tostring(char[][] array); public static String tostring(double[]array); public static String tostring(float[]array); public static String tostring(int[]array); public static String tostring(long[]array); public static String tostring(short[]array); public static String tostring(string[]array); /* * Inner class TransactionTP.ServiceInfo public class ServiceInfo { public Buffer buffer; public String name; // data // service name public int flags; public int cd; // describes service attributes // handle name, public ServiceInfo(long virtualaddress, int length, String public String tostring(); int flags, int cd); } // End inner class TransactionTP.ServiceInfo 7833 5080 009 C 7

Java Package Contents } // End class TransactionTP C.2. TransactionView Interface Contents The following is the skeleton of the public members of the TransactionView class: /* * TransactionView.java 1.00 00/07/25 package com.unisys.os2200.tmapi; public interface TransactionView { public TransactionTP.Buffer getbuffer(); public long getlength(); public String gettype(); public String getsubtype(); public String tostring(); } // End interface TransactionView C 8 7833 5080 009

Glossary A absolute element An OS 2200 machine-language element type. Depending on the element subtype, an absolute element can be an absolute produced by the Collector, a subsystem definition element, or one of several types of object modules produced by extended mode compilers or the Linking System. See also basic mode, Collector, extended mode, Linking System, object module. ACID properties The essential attributes of transaction processing systems. Atomicity: All changes that a transaction makes to a database are made permanent, or else all are nullified. Consistency: A successful transaction transforms a database from a previous valid state to a new valid state. Isolation: Changes that a transaction makes to a database are not visible to other operations until the transaction completes its work. Durability: Changes that a transaction makes to a database survive future system or media failures. advertise To make available a service offered by a server by using the XATMI interface. See also unadvertise, XATMI interface. AP See application program. AP-CRM interface An Open Group standard interface that application programs use to communicate with other application programs. Open Distributed Transaction Processing supports the XATMI AP-CRM interface. See also XATMI interface. API See application program interface. application Program logic that consists of client programs and service routines that define transactions and access resources under the control of a transaction manager (TM). See also application program, server program, transaction manager, Open Group Distributed Transaction Processing model. 7833 5080 009 Glossary 1

Glossary application group An OS 2200 group that consists of an integrated recovery database, audit trail, data dictionary (optional), and message retention files. Integrated recovery application groups are generally defined to be recoverable to prevent database corruption due to system, component, or program failures. Integrated recovery is provided only for users that are attached to an application group. Multiple application groups can be configured on one host. An application group that spans multiple host systems is called a concurrent application group. See also integrated recovery. application program (AP) (1) A single instance of a user program that performs one or more specific tasks. An AP defines transaction boundaries and accesses resources within those boundaries; it interacts with other system components using interfaces specified in the Open Group Distributed Transaction Processing model. An AP is a single thread of control involved in at most one global transaction at any time. See also global transaction, thread of control. (2) An Open Distributed Transaction Processing client program or service routine. See also client program, service routine, Open Group Distributed Transaction Processing model. application program interface (API) A set of callable functions or routines that an application programmer can use to request and carry out lower-level or common services. AP-RM interface An interface that provides application programs access to resources, such as databases and print servers. Examples of AP-RM interfaces include SQL and ISAM. AP-RM interfaces are not specified in the Open Group Distributed Transaction Processing model. See also application program, resource manager. AP-TM interface The Open Group standard interface that application programs use to specify global transaction boundaries to transaction managers. This interface is also known as the TX interface. See also global transaction, transaction boundaries, TX interface. ASCII COBOL Compiler The Unisys OS 2200 basic mode implementation of the COBOL programming language that is compatible with the COBOL 74 standard. See also basic mode, extended mode, COBOL Compiler. asynchronous service request A service request in which a requestor does not wait for a reply. Instead, the caller requests a reply at a later time or specifies that no reply is needed. See also service request, synchronous service request. atomicity A required property of transactions: The changes a transaction makes to a database are made permanent or are nullified entirely. See also ACID properties. AUTOTRAN An Open Distributed Transaction Processing configuration option that affects the execution of service routines. If a service routine is configured AUTOTRAN=ON in the TMSCONFIG file, it is automatically placed in transaction mode regardless of how it is called. See also TMSCONFIG file, transaction mode. Glossary 2 7833 5080 009

Glossary B bank (1) A data structure of computer hardware representing an area of main storage. This is called a physical bank. (2) A collection of related code, data, and control information that is the main subdivision of an OS 2200 object module element. This is called a virtual bank, logical bank, or bank template. Virtual banks are produced by compilers or assemblers and are loaded into physical banks. basic mode The execution mode that is compatible with 1100/60 systems. See also extended mode. boundary of transaction See transaction boundaries. buffer See typed buffer. buffer subtype A user-defined structure that specifies exactly how the data in an Open Group typed buffer is structured. The structure is based on the needs of application programs and database information to be exchanged. See also typed buffer, VIEW. BUFMAKE An Open Distributed Transaction Processing system administration tool that creates VIEW descriptions, C include elements, and COBOL COPY. See also VIEW. C C Compiler The OS 2200 implementation of the C programming language that is compatible with American National Standard C. chained mode A mode of execution in which a new global transaction starts implicitly in the application thread of control when the current global transaction completes. The transaction manager coordinates completion of the current transaction and starts a new (chained) transaction in the calling thread of control before it returns control to the application program. See also unchained mode. client program An application program (AP) that requests services from other APs. Clients can reside on any platform that supports clients anywhere on the network, but often handle the user interface portions of an application. A service routine can act as a client when it calls a transaction manager to start a new transaction. See also application program, global transaction, server program, service routine, transaction manager. 7833 5080 009 Glossary 3

Glossary client/server model A programming model in which application programs are structured as clients or servers. A client program is an application program that requests services to be performed. A server program is an entity that dispatches service routines to satisfy requests from client programs. A service routine is an application program module that performs one or more specific functions on behalf of client programs. See also client program, server program, service routine. CMS 1100 Software that provides and manages all communications into and out of OS 2200 host computers. CMS 1100 enables communication between applications on an OS 2200 host and Applications on other processors, including other OS 2200 hosts Users on networks to which CMS 1100 has access COBOL Compiler The OS 2200 extended mode implementation of the COBOL programming language that is compatible with the COBOL 85 standard. COBOL programming language See ASCII COBOL Compiler, UCS COBOL Compiler. Collector The OS 2200 software product that combines relocatable elements into an absolute element. See also absolute element, basic mode. commitment The event that ends a transaction and makes permanent all changes that were made to resources (such as databases) during that transaction. See also one-phase commit protocol, rollback, two-phase commit protocol. commitment coordinator The transaction manager that coordinates the completion of a specific global transaction. See also global transaction, transaction manager. commitment protocol The procedure that is followed to synchronize the completion of a transaction. See also one-phase commit protocol, rollback, two-phase commit protocol. communication resource manager (CRM) A system software component that enables one instance of the Open Group Distributed Transaction Processing model to access another instance, either inside or outside the TM domain to which the first instance belongs. An instance consists of one application program, one transaction manager, and one or more resource managers. See also instance of the model, TM domain, XATMI interface, Open Group Distributed Transaction Processing model. completion, transaction See transaction completion. Glossary 4 7833 5080 009

Glossary configuration file See TMSCONFIG file. consistency A required property of transactions: A database involved in a transaction is transformed from one valid state to another. See also ACID properties. consistent state A condition in which shared data is correct and valid. conversational communication A method of communication in which a client and server establish a connection and send messages back and forth. See also client program, server program. conversational service A service routine invoked by means of conversational communication from a client. When the connection is established and the service is invoked, the client and service can exchange data in a manner specific to the application. When the service returns, the connection is ended. See also request-response service. CRM See communication resource manager. D database (1) A data resource managed by a database management system (DBMS) or file access system. The DBMS or file access system acts as a resource manager (RM) to maintain the ACID properties for transactions that update the database. (2) (OS 2200) Open Distributed Transaction Processing applications can access database resources through the Universal Data System (UDS) models provided by the Data Management System (DMS 2200), Relational Data Management System (RDMS 2200), and Shared File System (SFS 2200). Open Distributed Transaction Processing applications can also access FCSS files. (3) See also ACID properties, database management system, Data Management System, FCSS file, Relational Data Management System, resource manager, Shared File System, Universal Data System. database management system (DBMS) Software that manages access and updates to shared database resources. See also database, resource manager. DBMS See database management system. departmental server A hardware platform that provides open interoperability, high productivity application services, distributed databases, transaction orientation, support of multiple workgroups, shared logical resources, network access, and application gateways. See also enterprise server, server program. 7833 5080 009 Glossary 5

Glossary Display Processing System (DPS 2200) An OS 2200 system that manages display-oriented transactions in an online environment. DPS 2200 provides facilities to define forms (screen templates), user profiles, security, and test environments. DPS 2200 can also handle messages for transaction processing (TIP/HVTIP) and online batch programs that use MCB. See also Message Control Bank. distributed transaction See global transaction. distributed transaction processing (DTP) A form of processing in which multiple application programs update multiple resources (such as databases) in a coordinated manner. Programs and resources can reside on one or more computers across a network. See also global transaction, Open Group Distributed Transaction Processing model. DMS 2200 See Data Management System. domain See TM domain. DPS 2200 See Display Processing System. DTP See distributed transaction processing. durability A required property of transactions: Changes a transaction makes to a database must survive future system or media failures. See also ACID properties. dynamic registration An event during which a resource manager (RM) contacts a transaction manager (TM) to become associated with a specific global transaction. RMs register dynamically after they are instructed by application programs (AP) to perform work. RMs can also be permanently registered with TMs. In this situation, RMs are contacted by TMs whenever APs start global transactions. See also global transaction, permanent registration, resource manager, transaction manager. E ECL ELMS See Executive Control Language. See Extended Language Message System. Glossary 6 7833 5080 009

Glossary end service An Open Distributed Transaction Processing service that needs to be executed by an Internet user. It can be a new generation service or a Heritage Application Access (HAA) service. enterprise server A platform type that provides open interoperability, high productivity application services, advanced database software, transaction processing, unlimited growth, nonstop/continuous processing, unattended operations, and high security. See also departmental server, server program. entry point The symbolic name or address of a word in an OS 2200 code (instruction) bank to which an executing activity can transfer. Before resolution, the entry point is a symbolic name; after resolution, it is an address. See also bank. event log The Open Distributed Transaction Processing log file that contains messages written from the Open Distributed Transaction Processing system or user application programs to record system events and errors. See also TMLS utility. event log server utility See TMLS utility. Exec See Executive system. Executive Control Language (ECL) The interface between programmers and the OS 2200 operating system. ECL provides a set of statements to Start and control runs Generate and execute programs Create, delete, copy, and otherwise manipulate files Send messages to the console and other terminals Executive request (1) The standard interface between programs and the Executive. An ER is an instruction that causes a special interrupt used to request Executive service (for example, time of day). (2) The service resulting from an Executive request. (3) See also Executive system, Executive Control Language. Executive system (Exec) The OS 2200 Executive system. An Executive is a routine that controls the execution of other routines. The Executive is the principal interface between the user and the system as a whole. It is responsible for such functions as time and space allocation, first-level input/output control and interrupt answering, logging of system accounting data, first-level debugging assistance, and protection against undesired interaction with other system users. See also Executive Control Language, Executive request. 7833 5080 009 Glossary 7

Glossary explicit rollback A rollback of a global transaction that an application program (AP) initiates by using the TX interface. An AP that initiates an explicit rollback must be the same AP that started the transaction. See also implicit rollback, rollback. Extended Language Message System (ELMS) A software product used by OS 2200 applications as a message storage and delivery system. ELMS also provides the ability to store and deliver messages that have been translated into different languages. extended mode The execution mode that allows 16 base registers, increased address space, and additional machine instructions. See also basic mode. F FCSS file A TIP file with a record format that programs can access by record number. An FCSS file can be a direct-access file or a Freespace file. See also file control superstructure, TIP file control. file control superstructure (FCSS) The primitive or function name for calls to TIP file control. The terms "FCSS" and "TIP file control" are generally used interchangeably. See also FCSS file, TIP file control. G global transaction A single unit of work that is performed by one or more application programs and one or more resource managers, possibly on different machines. An application program defines the start and end of a global transaction. A transaction manager coordinates a global transaction's initiation and completion (on behalf of an application program) by communicating with participating resource managers. An application program can also perform work outside of any global transaction (a nonglobal transaction). See also ACID properties, nonglobal transaction, resource manager, transaction manager, TX interface, Open Group Distributed Transaction Processing model. global transaction identifier See XID. Glossary 8 7833 5080 009

Glossary H heuristic completion In Open Group usage, a situation in which a resource manager (RM) unilaterally commits or rolls back changes that it made to shared resources during a global transaction, without knowing the global transaction's state. After an RM makes a heuristic decision, it may unlock shared resources and allow other global transactions to make further changes. Heuristic decisions that RMs make about changes to shared resources do not necessarily match decisions that transaction managers (TM) make about the associated global transactions. When RMs and TMs make opposite decisions, shared resources (databases) become inconsistent. See also ACID properties, global transaction, mixed-heuristic result, resource manager. High-Performance Transaction Processing for XATMI (HTP/x) OS 2200 system software that supports the transaction processing protocols defined in ISO/IEC 10026-3. These protocols allow heterogeneous computer systems to communicate in support of distributed transactions. The HTP/x interface, a component of the OSI-TP product, supports access to the OSI TP functions required by the Open Group CAE specification of the XATMI Application Programming Interface (XATMI API). It provides services to Initiate and accept or reject remote service requests both inside and outside of a global transaction Send and receive data Prepare, commit, and roll back transactions High-Performance Transaction Processing Interconnect (HTP/ic) (1) System software that provides the underlying connection between the ClearPath HMP Windows NT node and the custom node for Open Distributed Transaction Processing client/server applications using the FDDI link. HTP/ic facilitates communication to the HTP/x product, if available, and, ultimately, the Open Distributed Transaction Processing product on the custom node. HTP/ic is based on XATMI and OSI TP standards. (2) System software that provides a subset of HTP/x capabilities. Referred to as HTP/ic-2200, this version resides on the 2200 node and communicates with HTP/ic software on the Windows NT node. High-Volume Transaction Processing (HVTIP) An OS 2200 product used for applications that require a high rate of throughput and whose processing can pass through an arbitrary sequence of subprograms. An HVTIP program library is a TIP user file designated (through the TPUR utility) as a container for HVTIP program banks. See also Transaction Processing (TIP). HTP/ic HTP/x See High-performance Transaction Processing Interconnect. See High-performance Transaction Processing for XATMI. 7833 5080 009 Glossary 9

Glossary I ICP See initial control program. identifier, transaction See XID. implicit rollback A rollback of a global transaction that a transaction manager initiates when a resource manager responds negatively to the first phase of the two-phase commit protocol. See also explicit rollback, rollback, transaction manager, two-phase commit protocol. initial control program (ICP) An HVTIP main program that calls HVTIP subprograms. See also High-Volume Transaction Processing. instance of the model The set of computing entities that implement the functional components and interfaces of all or part of an application within the Open Group Distributed Transaction Processing model. Each instance supports one application program, one transaction manager, and one or more resource managers. See also resource manager, transaction manager, TM domain, Open Group Distributed Transaction Processing model. integrated recovery A combination of OS 2200 software products and features whose primary purpose is to synchronize database and message processing and recovery. Integrated recovery encompasses database recovery for the Exec, TIP file control, and UDS. It encompasses message recovery for MCB and CMS 1100. See also application group, Integrated Recovery Utility, Message Control Bank, message recovery, TIP file control, Universal Data System Control. Integrated Recovery Utility (IRU) A command-driven utility used after an OS 2200 system or application group failure to maintain file, database, and transaction message integrity and availability. IRU is the database component of integrated recovery for data in both UDS and TIP files. See also integrated recovery. isolation A required property of transactions: Changes a transaction makes to a database are not visible to other transactions until the transaction completes its work. See also ACID properties. J jump vector An OS 2200 MASM element that contains the instructions needed to jump from a referenced entry point to the correct bank offset of the actual entry point. Glossary 10 7833 5080 009

Glossary L linking The process of converting the output of a compilation to an executable form. This primarily involves uniting separately compiled object modules into a single program. OS 2200 extended mode linking is performed by the Linking System. See also Linking System. Linking System The OS 2200 software system that converts a program from the form produced by the compiler or assembler (object module) to a form the computer hardware can execute. See also linking, object module. LINK Processor The part of the OS 2200 Linking System that performs static linking. See also Linking System. M MAKEAP$NAME An Open Distributed Transaction Processing utility program used to build an application program name element. MAKEHVCALL An Open Distributed Transaction Processing utility program used to build HVTIP servers. mapping Using the OS 2200 Collector software to gather relocatable elements into an executable program called an absolute element. See also absolute element, basic mode, Collector. MASM See Meta-Assembler. mass storage A storage medium in which data can be organized and maintained in both a sequential and nonsequential manner. See also mass storage file. mass storage file A collection of records assigned to a mass storage medium. MAS utility An Open Distributed Transaction Processing utility processor used to build and link a server. See also server program. Message Control Bank (MCB) A Unisys software product that interfaces with the Communications Management System (CMS 1100) and transaction programs to provide message recovery and transaction scheduling. 7833 5080 009 Glossary 11

Glossary Meta-Assembler (MASM) The OS 2200 Meta-Assembler language. mixed-heuristic result In Open Group usage, a database inconsistency that occurs when a resource manager unilaterally rolls back an update and a transaction manager commits the associated global transaction (or the reverse). See also heuristic completion, resource manager, transaction manager. N Network Database Server for ClearPath OS 2200 The CODASYL-based data manager that provides a network database model. nonglobal transaction A transaction involving one or more resource managers in which a commitment, if any, is controlled solely by the application program and not by a transaction manager. Work performed by each resource manager preserves the ACID properties, but commitment is not coordinated between resource managers. See also ACID properties, global transaction, resource manager, transaction manager. O object module An OS 2200 extended mode element in a program file that is produced by a Universal Compiling System (UCS) compiler or the Linking System. The banks in an object module can be loaded into main storage and executed. The types of object modules are standard object modules, bound object modules, and zero overhead object modules. See also Linking System, Universal Compiling System, zero overhead object module. OLTP See online transaction processing. OLTP-TM2200 The installed product name for the Open Distributed Transaction Processing Transaction Manager. one-phase commit protocol An Open Group commitment protocol that a transaction manager can use when only one resource manager is updating resources. See also commitment, resource manager, transaction manager, two-phase commit protocol. online transaction processing A form of data processing in which users at terminals or workstations send messages to application programs, which update databases in real time. Glossary 12 7833 5080 009

Glossary Open Group An international nonprofit consortium dedicated to the advancement of open systems. Its primary activities include defining standards and branding products to ensure interoperability between the products of different vendors. Open Group Distributed Transaction Processing (DTP) model The distributed transaction processing model specified in standards developed by The Open Group. The Open Distributed Transaction Processing architecture is based on these standards. The model defines four components of a DTP system. Application programs (AP) define the boundaries of transactions and perform the actions that make up the transaction (typically database updates). Resource managers (RM) such as database management systems provide access to shared resources. Communication resource managers (CRM) allow application programs to communicate with each other. A transaction manager (TM) assigns unique identifiers (XID) to transactions, monitors the progress of transactions, and handles transaction completion or recovery. See also application program, communication resource manager, resource manager, transaction manager. Open Distributed Transaction Processing Pathway An Distributed Processing Middleware component that provides applications in the Intel (UnixWare or Windows NT) environment of a ClearPath IX server with a gateway to the Open Distributed Transaction Processing in the OS 2200 environment. This allows Windows NT or UnixWare applications to execute transactions against OS 2200 databases. See also client program. Open Systems Interconnect Distributed Transaction Processing (OSI-TP) The Unisys implementation of OSI TP communication protocols. The OSI-TP product adheres to the ISO 10026 standard and the NIST stable implementation agreements. OSI-TP provides interoperability and distributed transaction processing services for Unisys and other selected foreign vendors. Open Systems Interconnection A set of ISO standards that, when implemented, allows different computer systems from different vendors to communicate with each other. See also OSI TP. Open Systems Interconnection Transaction Processing (OSI TP) An ISO standard (ISO/IEC 10026-3) for protocols and services that establish dialogues and pass messages between client programs and service routines on different computers. OSI TP OSI-TP See Open Systems Interconnection Transaction Processing. See Open Systems Interconnect Distributed Transaction Processing. output message A transaction output message created by a user program, passed to the communications network, and transmitted to an external destination. 7833 5080 009 Glossary 13

Glossary P paradigm Synonym for model. pass-off message An OS 2200 message passed from one transaction program to another. permanent registration The registration of a permanent resource manager (RM) with a transaction manager (TM). The TM contacts the RM whenever application programs start global transactions. See also dynamic registration. prepare to commit The first phase of the Open Group two-phase commit protocol. During this phase, the transaction manager (TM) requests each resource manager (RM) that is participating in a global transaction to prepare associated updates and to guarantee that it can commit them. When an RM can commit updates, it replies affirmatively. A negative reply reports failure. See also global transaction, resource manager, transaction manager, two-phase commit protocol. presumed rollback The Open Group rollback protocol that resource managers (RM) involved in global transactions use after they fail and recover. After an RM recovers, it rolls back any RM-internal transaction that was active at the moment of failure. RM-internal transactions that were prepared before the failure are committed or rolled back based on instructions from the transaction coordinator. See also global transaction, prepare to commit, resource manager, RM-internal transaction, rollback, transaction manager. Q queue A sequence of items that are waiting to be processed. R reentrant server A type of server that can reexecute a TIP service routine without reloading the service routine code. Only the data requested by the service routine is changed. See also server program. registration, dynamic See dynamic registration. registration, permanent See permanent registration. Relational Database Server for ClearPath OS 2200 The Unisys data manager that provides a relational database model. See also Universal Data System (UDS). Glossary 14 7833 5080 009

Glossary requestor A generic term for a client or server program that is acting as a client. request/reply communication A method of communication in which a client sends a request and a server performs the task and returns a reply to the client. See also client program, server program. request-response service A service initiated by a request from a client application. The service routine receives a single request and provides (at most) a single response. The request and response are application data sent between the client program and service routine. See also conversational service. resource manager (RM) A system software component that manages a defined part of a computer's shared resources. Examples of RMs include database management systems, file access methods, and print servers. In the Open Group Distributed Transaction Processing model, changes that are made to an RM's shared resources are structured as recoverable, atomic transactions. These are referred to as RM-internal transactions. Transaction managers keep track of RM-internal transactions that are associated with global transactions and coordinate the completion of RM-internal transactions. See also ACID properties, database management system, Data Management System, FCSS file, Relational Data Management System, TIP file control, Open Group Distributed Transaction Processing model. RM-AP interface See AP-RM interface. RM-internal transaction A recoverable, atomic unit of work that is owned by a single resource manager (RM). In the Open Group Distributed Transaction Processing model, a global transaction consists of one or more RM-internal transactions that are owned by one or more RMs. Transaction managers coordinate the commitment of all RM-internal transactions that are associated with particular global transactions. See also global transaction, resource manager, transaction manager. RM-TM interface See TM-RM interface. rollback The event that ends a transaction and nullifies or undoes all changes to resources that were specified during that transaction. See also commitment. run A sequence of tasks linked together to form a self-contained unit of work. The user controls a run with a series of Executive control statements that tell the operating system what to do. The user starts a run with the @RUN statement and ends it with the @FIN statement. See also Executive Control Language, runstream. runstream The ECL statements, data, program lines, and other input that a programmer provides during the course of a run. See also Executive Control Language, run. 7833 5080 009 Glossary 15

Glossary Runtime System for Extended Mode Compilers A set of routines called by the executable output produced by the Language Support System. These routines provide support for input/output, storage management, mathematical functions, and miscellaneous utilities. S SCO UnixWare A popular version of the UNIX operating system. UnixWare software combines Symmetrical Multi-Processing (SMP) technologies from Unix System Laboratories, Inc. (USL), enhancement by Novell, Inc., and solution delivery from The Santa Cruz Operation, Inc. (SCO). SCO UnixWare has improved reliability and price/performance ratios. security server The result of building the security service into an OLTP batch, TIP, or HVTIP server. When the security service is called by a tpconnect statement, the security server executes. In the examples, it is named secsvr. security service A C code module supplied by Unisys and written in the form of a standard Open Distributed Transaction Processing service. It processes user-id authentication requests and if successful, calls an end service for that user. The owner can customize this code module to fit environmental needs. In the code and examples, the security service is named secsvc. server (1) In software terms, a server program. See server program. See also client program, service routine. (2) In hardware terms, a host system that provides services to other systems in a distributed processing configuration. See also departmental server, enterprise server. server dispatcher utility See TMBSD utility, TMHAAD utility, TMTSD utility. server group A logical grouping of servers that use the same resource manager. Server groups are defined in the *GROUPS section of the TMSCONFIG file. See also server program, TMSCONFIG file. server program A combination of predefined and user-written code that processes requests for services from clients and passes those requests to the appropriate service routines. See also client program, service routine. service request A client program calling a service. See also asynchronous service request, synchronous service request. Glossary 16 7833 5080 009

Glossary service routine An application program module that performs one or more specific functions on behalf of client programs. The structure of service routines (the mechanism by which they are invoked and terminated) is defined by the XATMI interface specification. See also client program, server program, XATMI interface. SFS 2200 See Shared File System. SGS See stream generation statement. Shared File System (SFS 2200) OS 2200 software used to open a file for input/output and to read, write, and close the file when specified. SFS 2200 is intended for use when files are shared by more than one run. The available data file formats are indexed and direct, depending on the programming language used. See also run, Universal Data System. SQL SSG step See Structured Query Language. See Symbolic Stream Generator. A recoverable unit of work (such as a database update) that application programs or subprograms perform. stream generation statement (SGS) A data unit consisting of a label and a series of fields and subfields that provides input for Symbolic Stream Generator (SSG) skeletons. A group of stream generation statements (SGS) forms a matrix for tables or lists of data. See also Symbolic Stream Generator. Structured Query Language (SQL) A specialized language for defining, retrieving, changing, and maintaining data in databases. End users can use SQL to perform ad hoc, interactive queries. Programmers can include SQL statements in applications written with high-level languages, such as C, C++, and COBOL. See also Relational Data Management System. subsystem An extended mode software subsystem, a collection of code and data banks that share A common set of protection attributes A common set of library code names and library search chains that define how the Linking System resolves symbolic references 7833 5080 009 Glossary 17

Glossary Symbolic Stream Generator (SSG) A general-purpose interpreter that manipulates symbolic streams, such as data images, ECL statements, correction images, and language source statements. It uses directions contained in a skeleton. See also Executive Control Language, stream generation statement. synchronous service request A service request in which a requestor waits for a reply. See also service request, asynchronous service request. T TD2200 utility A utility that listens for connection establishment requests from clients that request services through Pathway or BEA TUXEDO Workstation (/WS) software. See also TMSC processor, workstation. temporary program file (TPF$) A mass storage file assigned automatically by the Exec to each run. In a wide variety of program file and element manipulation operations, in the absence of an explicit file reference, TPF$ is assumed as the program file. See also Executive system, run. thread See thread of control. thread of control A thread of control is an operating system process and all of its context. This includes an address space, the single thread of control executing within that address space, and the required system resources. The context can include both locks the process has on shared resources and files the process has open. For OS 2200, a thread of control is equivalent to a program activity. TIP See Transaction Processing. TIP file control The Exec component that provides specialized high-performance application group record management. For example, TIP file control handles the input and output for TIP files, coordinates locking of TIP files, and provides service functions. See also FCSS file. TM See transaction manager. TMADMIN processor The interactive Open Distributed Transaction Processing processor used by the system administrator to examine and remove records from the recovery logging file. See also RLFUTIL processor. TM-AP interface See AP-TM interface. Glossary 18 7833 5080 009

Glossary TMBSD utility The Open Distributed Transaction Processing batch server dispatcher utility that automatically schedules batch servers for execution. See also TMSC processor. TMCOMMON subsystem The Open Distributed Transaction Processing extended mode software subsystem in main storage. See also subsystem. TM-CRM interface The Open Group standard interface that enables different TM domains to exchange information about global transactions. Transaction managers use this interface to instruct communication resource managers to perform various tasks, such as sending commitment instructions to transaction nodes. The TM-CRM interface is also known as the XA+ interface. See also communication resource manager, global transaction, TM domain, transaction manager. TM domain One or more instances of the Open Group Distributed Transaction Processing model that share a single transaction manager. An instance consists of one application program, one transaction manager, and one or more resource managers. See also instance of the model, transaction manager, Open Group Distributed Transaction Processing model. TMHAAD utility The Open Distributed Transaction Processing utility that interfaces with MCB to schedule existing TIP and HVTIP online batch programs for execution. See also TMSC processor. TMLS utility The Open Distributed Transaction Processing event log server utility that writes messages to the event log. See also TMSC processor. TM-RM interface The Open Group standard interface that transaction managers use to structure the work of resource managers into global transactions and to coordinate the completion or recovery of global transactions. The TM-RM interface is also known as the XA interface. See also resource manager, transaction manager. TMSCONFIG file A mass storage file that contains Open Distributed Transaction Processing configuration data about server programs, service routines, and other system resources. The TMSCON processor loads and unloads configuration data between a TMSCONFIG file and the directory services database of the TMCOMMON subsystem. See also TMCOMMON subsystem, TMSCON processor. TMSC processor The Open Distributed Transaction Processing background batch run that controls TMSC utilities. See also TD2200 utility, TMBSD utility, TMHAAD utility, TMLS utility, TMTIMER utility, TMTRACER utility, TMTSD utility. 7833 5080 009 Glossary 19

Glossary TMSCON processor The Open Distributed Transaction Processing processor that updates configuration data in the TMCOMMON subsystem. The TMSCON processor processes data stored in TMSCONFIG files. See also TMCOMMON subsystem, TMSCONFIG file. TMSDUMP processor The Open Distributed Transaction Processing processor that produces a nondestructive memory dump of the TMCOMMON subsystem upon request. TMTIMER utility The Open Distributed Transaction Processing thread timer utility that wakes up timedout threads. See also TMSC processor. TMTRACER utility The Open Distributed Transaction Processing trace log server utility that traces execution of clients or servers. See also TMSC processor. TMTSD utility The Open Distributed Transaction Processing server dispatcher background utility that automatically starts TIP and HVTIP servers in response to queued service requests. See also TMSC processor. TPF$ See temporary program file. tpreturn() The C-language template for sending a reply message from a service routine and terminating the service routine. See also service routine. TPSVCINFO A data structure that C-language servers use to hold data associated with service requests. transaction A complete unit of work that transforms a database from one consistent state to another. In distributed transaction processing (DTP), a transaction can include multiple units of work performed on one or more systems. See also ACID properties, consistent state, distributed transaction processing, global transaction, transaction processing. transaction boundaries The start and end of a global transaction. Application programs define transaction boundaries by using the TX interface. See also global transaction, transaction manager, TX interface. transaction code The name of a TIP transaction program. Glossary 20 7833 5080 009

Glossary transaction completion Commitment or rollback of a transaction. Commitment ends a transaction and makes permanent all changes to resources that were specified during that transaction. Rollback ends a transaction and nullifies or undoes all changes to resources that were specified during that transaction. See also commitment coordinator, one-phase commit protocol, two-phase commit protocol. Transaction Demarcation (TX) interface See TX interface. transaction, global See global transaction. transaction identifier See XID. transaction manager (TM) (1) A system software component that manages global transactions on behalf of application programs. TMs coordinate commands from application programs and communication resource managers to start and complete global transactions by communicating with all resource managers (RM) that are participating in those transactions. When RMs fail during global transactions, TMs help RMs decide whether to commit or roll back pending global transactions. See also global transaction, transaction, Open Group Distributed Transaction Processing model. (2) Open Distributed Transaction Processing software products that support application programs running on OS 2200, MCP, and TUXEDO operating systems. transaction mode (1) A mode of execution for an application program in which the application program is performing work under the control of a transaction manager (TM). The transaction manager controls initiation and completion of the transaction and issues all necessary thread-control commands. (2) In traditional OS 2200 transaction processing, a mode of execution that takes priority over batch mode and demand mode. (3) See also thread of control, transaction, transaction manager. transaction, nonglobal See nonglobal transaction. transaction processing A form of immediate data processing in which user requests are entered directly to the terminal and online programs satisfy the requests (for example, by updating database files and displaying output messages). An OS 2200 transaction processing environment is also called a TIP environment. See also transaction, Transaction Processing (TIP). Transaction Processing (TIP) The Unisys software that provides a form of immediate data processing in which user requests are entered directly at the terminal and online programs satisfy the requests (for example, by updating database files and displaying output messages). An OS 2200 transaction processing environment is also called a TIP environment. See also High-Volume Transaction Processing (HVTIP). 7833 5080 009 Glossary 21

Glossary transaction program In a Transaction Processing (TIP) environment, a high-priority program that executes in OS 2200 transaction mode. See also transaction code, transaction mode. transaction properties See ACID properties. TUXEDO A software product that is based on the Open Group model for distributed transaction processing (DTP). TUXEDO was developed by AT&T, sold to Novell, and is currently owned by BEA Systems. TUXEDO and other Open Group compliant DTP software (including the Unisys product Open Distributed Transaction Processing) allows organizations to develop applications that execute transactions across multiple systems and database types. two-phase commit protocol An Open Group protocol that transaction managers (TM) and resource managers (RM) use to commit or roll back global transactions. During the first phase, the TM instructs RMs to prepare work for commitment and to guarantee commitment. During the second phase, the TM instructs RMs to commit or roll back work. The two-phase commit protocol ensures the atomicity of global transactions. See also ACID properties, commitment, global transaction, one-phase commit protocol. TX interface The Open Group Transaction Demarcation (TX) application program interface (API) used by application programs (AP) to call the transaction manager. APs use the TX interface to define the boundaries of global transactions and direct the completion of those transactions. See also application program, application program interface, transaction manager. typed buffer A buffer (supported by the XATMI interface) into which application programs (AP) place data to be sent to other APs. A typed buffer has an associated type (and possibly a subtype) that specifies the meaning or interpretation of the data. The type and subtype together correspond to a host-language structure definition. The buffer types supported for C, COBOL, and Java are X_OCTET, X_COMMON, and X_C_TYPE. See also application program, XATMI interface. U UCF UDS See User Communication Form. See Universal Data System. unadvertise To temporarily suspend availability of a service offered by a server by using the XATMI interface. See also advertise, XATMI interface. Glossary 22 7833 5080 009

Glossary unchained mode A mode of execution in which a new transaction must be explicitly started by an application program (AP). A new transaction does not implicitly start when a previous transaction completes (as with chained mode). The TX interface allows APs to specify chained or unchained mode. An AP can use unchained mode to perform work outside of global transactions. See also application program, chained mode, global transaction, TX interface. Universal Data System (UDS) An expandable, modular collection of related Unisys products used for database management in an integrated recovery environment. UDS supports three database management software products: Network Database Server for ClearPath on OS 2200, Relational Database Server for ClearPath on OS 2200, and Shared File System (SFS 2200). See also Data Management System, integrated recovery, Relational Data Management System, Universal Data System Control. Universal Database Control The UDS online data and file manager. It controls data storage and retrieval between main storage and mass storage for all UDS files. See also Universal Data System. UnixWare See SCO UnixWare. User Communication Form (UCF) A form for communicating comments and problems concerning Unisys products and documentation. V VADD utility A utility used to install a VIEW. Using the VADD utility, you can install a defined VIEW, update VIEWs already installed, and generate C include elements and COBOL COPY elements for use by application programs. See also buffer subtype, VIEW. VDEL utility A utility used to delete an installed VIEW. See also buffer subtype, VIEW. VGET utility A utility used to obtain information about an installed VIEW. You can also use the VGET utility to generate C include elements and COBOL COPY elements for use by application programs. See also buffer subtype, VIEW. VIEW An OLTP construct defined when the name of a formatted definition of the data structure for a buffer subtype is associated with an Open Group typed buffer. See also typed buffer. 7833 5080 009 Glossary 23

Glossary W WebTx security gateway A specialized WebTx gateway that runs on a Windows NT or UnixWare Web server machine. This gateway is built as a client application to interoperate in conversation mode with the Open Distributed Transaction Processing security service. This code module can be customized to meet environmental needs. workstation A transaction-oriented platform that provides open interoperability, personal productivity, distributed databases, user access to the information network, device and resource sharing, and a common user interface. See also departmental server, enterprise server. World Wide Web (WWW) A world-wide network (a subset of the Internet) that is populated by hyperlinked documents. Web browsers such as Microsoft Internet Explorer and Netscape hide much of the complexity of the WWW and allow users to view multimedia documents and easily jump from one document to another and from one Web site to another. Also referred to as the Web. Glossary 24 7833 5080 009

Glossary X XA interface The TM-RM interface that transaction managers use to structure the work of resource managers into global transactions and to coordinate the completion or recovery of global transactions. See also resource manager, transaction manager. XA+ interface The TM-CRM interface that enables different TM domains to exchange information about global transactions. Transaction managers use this interface to cooperate with communication resource managers to perform various tasks, such as creating transaction nodes and coordinating the commitment of those nodes. Although the XA+ interface is identified in The Open Group DTP model, it is not yet a formallyspecified interface. See also communication resource manager, global transaction, TM domain, transaction manager. XATMI interface An AP-CRM interface that enables application programs to use request-response communication and conversational communication during global transactions. See also client/server model, communication resource manager. XID X/Open A unique identifier that identifies all work done on behalf of a global transaction. The TM generates a new XID at the request of an application program (AP) to begin a new transaction or the next transaction in a chain. The communication resource manager (CRM) generates an XID with a new branch qualifier when a new branch is added to a transaction. The XID identifies all work done for a single global transaction on one OS 2200 system. See also application program, chained mode, global transaction, transaction manager. See Open Group. Z zero overhead object module (ZOOM) An OS 2200 extended mode TIP or HVTIP object module produced by static linking (LINK Processor). See also object module, High-Volume Transaction Processing, LINK Processor, Transaction Processing (TIP). ZOOM See zero overhead object module. 7833 5080 009 Glossary 25

Glossary Glossary 26 7833 5080 009

Index A absolute element named with XQT parameter, MAS utility, 5-7 acall() function, 2-15 ACID properties, 2-1 ACOB parameter, MAS utility, 5-6 ACOBTIP parameter, MAS utility, 5-6 ACOB-TIPLIB elements, 7-7, 7-13 advertising services not supported for JVM on OS 2200, A-2 allocate() function, 2-16 AP parameter, MAS utility, 5-6 AP$NAME, 6-6, 6-11, 6-15, 7-7, 7-13, 7-18 application programs (AP) classification of, 2-3 client programs, 2-3, 2-8 server programs, 2-6 service routines, 2-7 Application to Transaction Manager specification (See XATMI interface) ASCII COBOL A option, MAS utility, 5-9 ACOB parameter, MAS utility, 5-6, 5-7 ACOBTIP parameter, MAS utility, 5-6 ACOB-TIPLIB elements, 7-7, 7-13 COPY elements, generating, 3-7, 3-13 DBBANKSIZE parameter, MAS utility, 5-5 library elements, 7-7, 7-13 MEMBLOCKS parameter, MAS utility, 5-5 R option, MAS utility, 5-9 reentrant server, 5-9 TIP parameter, MAS utility, 5-7 TPSVRDONE routine, 8-6 TPSVRINIT routine, 8-5 typed buffers, 2-9 X option, MAS utility, 5-10 XATMI services, 2-14, 2-15 ASCII COBOL Compiler data types for typed buffers, equivalents, 3-4 diagnostic services, 2-18 TX services, 2-17 asynchronous service request, 2-4, 2-13, 2-14, 2-15 AUTOTRAN configuration, 2-11 B bankno parameter, MAS utility, 5-8 basic mode servers A option, MAS utility, 5-9 batch B option, MAS utility, 5-9 building, 7-14 components of, 7-18 MAKESERVER addstream example, 7-16 MAS call, 7-15 C$S333, 7-6, 7-7, 7-13, 7-18 HVTIP building, 7-1 components of, 7-7 MAKESERVER addstream example, 7-4 MAS call, 7-3 V option, MAS utility, 5-9 X option, MAS utility, 5-10 modifying execution of, 8-1 TIP building, 7-8 components of, 7-13 MAKESERVER addstream example, 7-11 MAS call, 7-10 T option, MAS utility, 5-9 TPSVRDONE routine, 8-6 TPSVRINIT routine, 8-5 batch servers AP parameter, MAS utility, 5-6 B option, MAS utility, 5-9 basic mode building, 7-14 components of, 7-18 MAKESERVER addstream example, 7-16 MAS call, 7-15 7833 5080 009 Index 1

Index extended mode building, 6-11 components of, 6-15 MAKESERVER addstream example, 6-13 MAS call, 6-12 G option, MAS utility, 5-9 modifying execution of, 8-1, 8-2, 8-3, 8-5, 8-6 starting, 5-21 begin_thread, B-2 buffer subtypes described, 2-10 type directory, 3-1 using, 3-1, 3-2 VADD utility, 3-6 VDEL utility, 3-12 VGET utility, 3-13 VIEW format, 3-2, 3-5 buffers (See buffer subtypes; typed buffers) BUFMAKE and VADD compared, 3-44 comparison diagram, 3-45 BUFMAKE processor command and command parameter table, 3-38 command parameters, 3-38 commands, 3-38 continuation character, 3-41 example VIEW output, 3-44 general description, 3-32 preview, 3-31 starting processor, 3-37 termination output, 3-41 values for command parameters, 3-38 C C (See C functions; C Compiler) C Compiler diagnostic services, 2-18 C Compiler TX functions, 2-17 XATMI communications functions, 2-13 C Compiler include elements, generating, 3-7 C Compiler include elements, generating, 3-13 C Compiler servers, MAS utility, 5-9 C Compiler servers, MAS utility, 5-11 C Compiler tpsvrinit() routine, 8-2 C Compiler tpsvrdone() routine, 8-3 C functions diagnostic services, 2-18 elog(), 2-18 getdiag(), 2-18 service advertisement, 2-14, 2-15 tpacall(), 2-13 tpadvertise(), 2-14 tpalloc(), 2-13 tpcall(), 2-13 tpcancel(), 2-13 tpconnect(), 2-13 tpdiscon(), 2-13 tpfree(), 2-13 tpgetrply(), 2-13 tprealloc(), 2-13 tprecv(), 2-13 tpreturn(), 2-13 tpsend(), 2-13 tptypes(), 2-13 tpunadvertise(), 2-14 tx_begin(), 2-16, 2-17 tx_close(), 2-16, 2-17 tx_commit(), 2-16, 2-17 tx_info(), 2-16, 2-17 tx_open(), 2-16, 2-17 tx_rollback(), 2-16, 2-17 tx_set_commit_return(), 2-16, 2-17, A-2 tx_set_transaction_control(), 2-17, 2-18 tx_set_transaction_timeout(), 2-17 userlog(), 2-18, 8-3 C$JV, 6-6 C$S333, 7-6, 7-7, 7-13, 7-18 C$SMCn, 7-14 CALL$MNQ, 7-6, 7-7 call() function, 2-15 cancel() function, 2-15 CBEP$$TM, 7-7, 7-14, 7-18 client name and type, specifying on JMAC utility call, 4-5, 4-6 client programs characteristics of, 2-3, 2-9 functions of, 2-8 clients building with the JMAC utility, 4-1, 4-3 JMAC utility, building with, 4-1, 4-3 COBOL (See ASCII COBOL; COBOL routines; COBOL Compiler) Index 2 7833 5080 009

Index COBOL Compiler COPY elements, generating, 3-7, 3-13 data types for typed buffers, equivalents, 3-4 diagnostic services, 2-18 tpsvrdone() routine, 8-3 tpsvrinit() routine, 8-2 TX services, 2-17 typed buffers, 2-9 U option, MAS utility, 5-9 XATMI services, 2-14, 2-15 COBOL routines communications, 2-14 diagnostic services, 2-18 ELOG_, 2-18 GETDIAG_, 2-18 service advertisement, 2-15 service initialization, 2-15 TPACALL, 2-14 TPADVERTISE, 2-15 TPCALL, 2-14 TPCANCEL, 2-14 TPCONNECT, 2-14 TPDISCON, 2-14 TPGETRPLY, 2-14 TPRECV, 2-14 TPRETURN, 2-14 TPSEND, 2-14 TPSVCSTART, 2-15 TPUNADVERTISE, 2-15 TXBEGIN, 2-17 TXCLOSE, 2-17 TXCOMMIT, 2-17 TXINFO, 2-17 TXOPEN, 2-17 TXROLLBACK, 2-17 TXSETCOMMITRET, 2-17, A-2 TXSETTIMEOUT, 2-17 TXSETTRANCTL, 2-17 USERLOG_, 2-18 commit_thread, B-2 commitment of transaction, 2-11 communication resource manager (CRM), 2-4 communications buffer subtypes, 3-1 buffers (See typed buffers) Open Group protocols, 2-9 XA functions and Universal Database Control, B-2 XATMI functions, 2-13, 2-14, 2-15 compatibility issues for OLTP-TM2200 level 5R1 with level 4R1, A-3 connect() function, 2-15 conversational services, 2-4 CRM (See communication resource manager) CRM$ACCESS, 7-7, 7-14, 7-18 D data type translation client perspective, 3-37 server perspective, 3-36 DBBANKSIZE parameter, MAS utility, 5-5 diagnostic services C Compiler functions, 2-18 COBOL routines, 2-18 disconnect() function, 2-15 DTP environment systems and step control actions, B-3 ClearPath IX servers, 2-1, 2-9 FCSS, B-1 systems that support Open Group standards, 2-1, 2-9, B-1 Universal Database Control, B-1 E element parameter, MAS utility, 5-8 elog() function, 2-18 ELOG_ routine, 2-18 end service, 9-1 end_thread, B-2 examples MAKECLIENT addstreams batch extended mode client, 4-7 make-form file table, 5-5 MAKESERVER addstreams batch basic mode server, 7-16 batch extended mode server, 5-13, 6-13 HVTIP basic mode server, 7-4 HVTIP extended mode server, 6-4 TIP basic mode server, 7-11 TIP extended mode server, 6-9 MAS utility batch basic mode server, 7-15 batch extended mode server, 5-11, 6-12 HVTIP basic mode server, 7-3 HVTIP extended mode server, 6-3 TIP basic mode server, 7-10 TIP extended mode server, 6-8 7833 5080 009 Index 3

Index TPSVRDONE routine (default), 8-6 tpsvrdone() routine, 8-3 TPSVRINIT routine (default), 8-5 tpsvrinit() routine, 8-3 userlog() function, 8-3 VADD utility call, 3-8, 3-27 VDEL utility call, 3-12 VGET utility call, 3-15 VIEW format, 3-2, 3-5 extended mode servers batch B option, MAS utility, 5-9 building, 6-11 components of, 6-15 G option, MAS utility, 5-9 MAKESERVER addstream example, 6-13 MAS call, 6-12 C option, MAS utility, 5-9 HVTIP building, 6-2 components of, 6-6 MAKESERVER addstream example, 6-4 MAS call, 6-3 V option, MAS utility, 5-9 X option, MAS utility, 5-10 MAS utility, 5-11 modifying execution of, 8-1 TIP building, 6-7 components of, 6-11 MAKESERVER addstream example, 6-9 MAS call, 6-8 T option, MAS utility, 5-9 tpsvrdone() routine, 8-3 tpsvrinit() routine, 8-2 U option, MAS utility, 5-9 F FCSS proprietary interface, B-1 step control actions and TX functions, B-3 free() function, 2-16 functions (See C functions; COBOL routines) G getdiag() function, 2-18 GETDIAG_ routine, 2-18 getreply() function, 2-15 gettpurcode() function, 2-15 global transactions, defined, 2-2 H header file translation, 3-37 Heritage Application Access using BUFMAKE, 3-31 High-Volume Transaction Processing (HVTIP) (See HVTIP servers) HVCALLS, 6-6 HVTIP servers ACOBTIP parameter, MAS utility, 5-6 bankno parameter, MAS utility, 5-8 basic mode building, 7-1 components of, 7-7 MAKESERVER addstream example, 7-4 MAS call, 7-3 element parameter, MAS utility, 5-8 extended mode building, 6-2 components of, 6-6 MAKESERVER addstream example, 6-4 MAS call, 6-3 G option, MAS utility, 5-9 library number, MAS utility, 5-8 modifying execution of, 8-1, 8-3, 8-5, 8-6 starting, 5-21 TIP parameter, MAS utility, 5-7 TIPABSCALLSS parameter, Exec, 7-2, 7-9 V option, MAS utility, 5-9, 5-10 version parameter, MAS utility, 5-8 J Java functions free(), 2-16 Java functions acall(), 2-15 allocate(), 2-16 call(), 2-15 cancel(), 2-15 connect(), 2-15 disconnect(), 2-15 getreply(), 2-15 gettpurcode(), 2-15 Index 4 7833 5080 009

Index reallocate(), 2-16 receive(), 2-15 returnresults(), 2-16 send(), 2-16 types(), 2-16 JMAC utility call format, 4-5, 4-6 client name, specifying, 4-6 client type, specifying, 4-5 MAKECLIENT runstream, 4-1, 4-7 make-form format, 4-6 overview, 4-1 procedures for building clients, 4-3 JVM on OS 2200 XATMI communications functions, 2-15 JVM on OS 2200 View2java, 3-15 JVM on OS 2200 advertising services, A-2 L libraries (See also C functions; COBOL routines) ACOB-TIPLIB, 7-7, 7-13 HVTIP library number, specifying, 5-8 TX interface ASCII COBOL Compiler, 2-17 C Compiler, 2-17 COBOL Compiler, 2-17 XATMI interface ASCII COBOL, 2-14 C Compiler, 2-13 COBOL Compiler, 2-14 JVM on OS 2200, 2-15 LLMS return status, 9-39 LOCAL parameter, MAS utility, 5-7 M MAKECLIENT addstream examples batch extended mode client, 4-7 executing, 4-3 make-form format file table, 5-5 HVTIP library number, 5-8 JMAC utility parameters, 4-6 MAS utility parameters, 5-11 parameter table, 5-5 service routine names, 5-8 service routine table, 5-7 structure, 4-3, 5-4 MAKESERVER addstream examples batch basic mode server, 7-16 batch extended mode server, 5-13, 6-13 HVTIP basic mode server, 7-4 HVTIP extended mode server, 6-4 TIP basic mode server, 7-11 TIP extended mode server, 6-9 executing, 5-4 MAPHVTIP skeleton, 7-6, 7-8 MAS utility ACOB parameter, 5-6 ACOBTIP parameter, 5-6 AP parameter, 5-6 call format, 5-9, 5-10, 5-11 DBBANKSIZE parameter, 5-5 examples batch basic mode server, 7-15 batch extended mode server, 5-11, 6-12 HVTIP basic mode server, 7-3 HVTIP extended mode server, 6-3 TIP basic mode server, 7-10 TIP extended mode server, 6-8 executable element name, 5-7 LOCAL parameter, 5-7 make-form file table, 5-5 format, 5-11 parameter table, 5-5 service routine table, 5-7 MAKESERVER runstream, 5-2, 5-13 MEMBLOCKS parameter, 5-5 overview, 5-2 procedures for building servers, 5-3 security service, 9-12 server name, specifying, 5-10 server type, specifying, 5-9 TIP parameter, 5-7 TPSVRDONE parameter, 5-5 routine, 5-7 TPSVRINIT parameter, 5-5 routine, 5-7 XQT parameter, 5-7 MEMBLOCKS parameter, MAS utility, 5-5 7833 5080 009 Index 5

Index N NAME$ACCESS, 7-7, 7-14, 7-18 nested call feature, 5-9 nonglobal transactions, 2-2, B-4 O OCMS activity for the security service, 9-3 OLTP-TM2200 level 5R1 compatibility issues with level 4R1, A-3 omit_thread, B-2 Open Distributed Transaction Processing systems ClearPath IX servers, 2-1, 2-9 ClearPath NX servers, 2-1, 2-9 systems that support Open Group standards, 2-1, 2-9, B-1 typed buffers, 3-2 VIEWs, 3-2 Open Group communication models, 2-4 conversational communication model, 2-4 request-response communication model, 2-4 specifications Application to Transaction Manager (See XATMI interface) Transaction Demarcation (See TX interface) XA functions, B-2 typed buffers, 2-10, 3-2 Open Group DTP environment systems ClearPath IX servers, 2-1, 2-9 ClearPath NX servers, 2-1, 2-9 systems that support Open Group standards, 2-1, 2-9, B-1 operational considerations unsupported TX calls tx_set_commit_return (C Compiler), A-2 TXSETCOMMITRET (COBOL Compiler and ASCII COBOL Compiler), A-2 P parameter, MAS utility, 5-7 prepare_thread, B-2 R reallocate() function, 2-16 receive() function, 2-15 recover_thread, B-2 reentrant server, 5-9 request-response services, 2-4 resource manager FCSS, B-1, B-3 in global transaction, 2-2 step control actions and TX functions, B-3 UDS, B-1, B-3 restrictions, A-1 returnresults() function, 2-16 rollback of transaction, 2-11 ROQ return status, 9-41 S scode, make-form, 5-8 security server, 9-1 security service customization, 9-14 definition, 9-1 LLMS return status, 9-39 MAS utility, 9-12 message header, 9-34 OCMS activity, 9-3 password (new), 9-7 ROQ return status, 9-41 SESSION$CTRL interface, 9-3 source code, 9-4, 9-15 Transaction Integrator considerations, 9-4, 9-14 VIEWs, 9-32 send() function, 2-16 server name and type, specifying on MAS utility call, 5-9, 5-10 SERVER$MAIN, 6-6, 6-11, 6-15, 7-7, 7-14, 7-18 SERVER$MAINB, 7-7 servers building with the MAS utility, 5-1, 5-2, 5-3 characteristics of, 2-3 components of, 2-4 execution order, 2-7 functions of, 2-6 initializing, 8-2, 8-5 MAS utility, building with, 5-1, 5-2, 5-3 modifying execution of, 8-1, 8-2, 8-3, 8-5, 8-6 server main program, 2-4 Index 6 7833 5080 009

Index starting, 5-21 structure of, 2-5 terminating, 8-3, 8-6 TPSVRDONE routine, 8-6 tpsvrdone() routine, 2-7, 8-3 TPSVRINIT routine, 8-5 tpsvrinit() routine, 2-7, 8-2 service routines bankno parameter, MAS utility, 5-8 characteristics of, 2-3 element parameter, MAS utility, 5-8 functions of, 2-7 libno parameter, MAS utility, 5-8 make-form, MAS utility, 5-7 names, make-form, 5-8 scode parameter, make-form, 5-8 security service, 9-1 types of, 2-7 version parameter, MAS utility, 5-8 services advertising, functions, 2-14, 2-15 initializing, XATMI functions, 2-15 SESSION$CTRL interface, 9-3 SREPT$ACCESS, 7-7, 7-14, 7-18 SREPTABLE, 6-7, 6-11, 6-15, 7-7, 7-14, 7-18 starting servers, 5-21 step control actions and TX functions, B-3 for nonglobal transactions, B-4 supported Open Group typed buffers X_C_TYPE, 2-10, 3-2 X_COMMON, 2-10, 3-2 X_OCTET, 2-10, 3-2 synchronous service request, 2-4, 2-13, 2-14, 2-15 T thread, Exec, B-3 TIP file access, B-3, B-4 parameter, MAS utility, 5-7 TIP servers ACOBTIP parameter, MAS utility, 5-6 AP parameter, MAS utility, 5-6 basic mode building, 7-8 components of, 7-13 MAKESERVER addstream example, 7-11 MAS call, 7-10 extended mode building, 6-7 components of, 6-11 MAKESERVER addstream example, 6-9 MAS call, 6-8 G option, MAS utility, 5-9 modifying execution of, 8-1, 8-2, 8-3, 8-5, 8-6 R option, MAS utility, 5-9 reentrant server, 5-9 starting, 5-21 T option, MAS utility, 5-9 TIP parameter, MAS utility, 5-7 TIPABSCALLSS parameter, Exec, 7-2, 7-9 TIPABSCALLSS parameter, Exec, 7-2, 7-9 TM$RUN file, 3-37 TMBSD utility, 5-21 TPACALL routine, 2-14 tpacall() function, 2-13 TPADVERTISE routine, 2-15 tpadvertise() function, 2-14 tpalloc() function, 2-13 TPCALL routine, 2-14 tpcall() function, 2-13 TPCANCEL routine, 2-14 tpcancel() function, 2-13 TPCONNECT routine, 2-14 tpconnect() function, 2-13 TPDISCON routine, 2-14 tpdiscon() function, 2-13 tpfree() function, 2-13 TPGETRPLY routine, 2-14 tpgetrply() function, 2-13 tprealloc() function, 2-13 TPRECV routine, 2-14 tprecv() function, 2-13 TPRETURN routine, 2-14 tpreturn() function, 2-13 TPSEND routine, 2-14 tpsend() function, 2-13 TPSS$ACCESS, 7-7, 7-14, 7-18 TPSVCSTART routine, 2-15 TPSVRDONE parameter, MAS utility, 5-5 TPSVRDONE routine basic mode server processing, 7-7, 7-14, 7-19 default code, 8-6 function of, 2-7 LOCAL parameter, MAS utility, 5-7 modifying, 8-6 tpsvrdone() routine example, 8-3 7833 5080 009 Index 7

Index extended mode server processing, 6-7, 6-11, 6-15 function of, 2-7 modifying, 8-3 TPSVRDSYSDTA, 7-7, 7-14, 7-19 TPSVRINIT parameter, MAS utility, 5-5 TPSVRINIT routine basic mode server processing, 7-7, 7-14, 7-19 default code, 8-5 function of, 2-7 LOCAL parameter, MAS utility, 5-7 modifying, 8-5 tpsvrinit() routine example, 8-3 extended mode server processing, 6-7, 6-11, 6-15 function of, 2-7 modifying, 8-2 TPSVRISYSDTA, 7-8, 7-14, 7-19 tptypes() function, 2-13 TPUNADVERTISE routine, 2-15 tpunadvertise() function, 2-14 Transaction Integrator security gateway, 9-1, 9-4, 9-14 transaction mode AUTOTRAN configuration, 2-11 defined, 2-2 tx_begin(), 2-11 transactions AUTOTRAN configuration, 2-11 boundaries (TX services), 2-11 commitment of, 2-11 definition of, 2-1 global, defined, 2-2 nonglobal, 2-2, B-4 rollback of, 2-11 TX interface and step control actions, B-3 ASCII COBOL Compiler services, 2-17 C Compiler functions, 2-17 COBOL Compiler services, 2-17 transaction boundaries, defining, 2-11 tx_begin() function, 2-16, 2-17 tx_close() function, 2-16, 2-17 tx_commit() function, 2-16, 2-17 tx_info() function, 2-16, 2-17 tx_open() function, 2-16, 2-17 tx_rollback() function, 2-16, 2-17 tx_set_commit_return() function, 2-16, 2-17, A-2 tx_set_transaction_control() function, 2-17, 2-18 tx_set_transaction_timeout() function, 2-17 TXBEGIN routine, 2-17 TXCLOSE routine, 2-17 TXCOMMIT routine, 2-17 TXINFO routine, 2-17 TXOPEN routine, 2-17 TXROLLBACK routine, 2-17 TXSETCOMMITRET routine, 2-17, A-2 TXSETTIMEOUT routine, 2-17 TXSETTRANCTL routine, 2-17 type directory, 3-1 typed buffers buffer subtypes, 2-10, 3-1 COBOL programs using, 2-9, 3-4 Open Group types, 2-10 X_C_TYPE, 2-10, 3-2 X_COMMON, 2-10, 3-2, 3-4 X_OCTET, 2-10, 3-2 XATMI functions, 2-9, 2-13, 2-16 types() function, 2-16 U Universal Database Control functions, B-2 step control actions and TX functions, B-3 Universal Database Control proprietary interface, B-1 unsupported TX calls tx_set_commit_return (C Compiler), A-2 TXSETCOMMITRET (COBOL Compiler and ASCII COBOL Compiler), A-2 userlog() function, 2-18 USERLOG_ routine, 2-18 utilities MAS (make a server), 5-1 TMBSD (batch server dispatcher), 5-21 VADD, 3-6 VDEL, 3-12 VGET, 3-13 VIEW, 3-6 V VADD and BUFMAKE compared, 3-44 comparison diagram, 3-45 VADD processor purpose, 3-46 VADD utility Index 8 7833 5080 009

Index BDT initialization, 3-6 call format, 3-7 COBOL COPY elements, generating, 3-7 example of calling, 3-8, 3-27 using, 3-6 VALTAB entries HVTIP basic mode server, 7-2 HVTIP extended mode server, 6-2 TIP basic mode server, 7-8 TIP extended mode server, 6-8 VDEL utility BDT initialization, 3-6 call format, 3-12 example of calling, 3-12 using, 3-12 version parameter, MAS utility, 5-8 VGET utility BDT initialization, 3-6 C include elements, generating, 3-7, 3-13 call format, 3-13 COBOL COPY elements, generating, 3-13 using, 3-13 VIEW format compatibility of, 3-2 example of, 3-2, 3-5 VIEW translation, 3-36 VIEW utilities BDT initialization, 3-6 BUFMAKE, 3-31 VADD, 3-6, 3-8, 3-27 VDEL, 3-12 VGET, 3-13, 3-15 X X_C_TYPE typed buffers, 2-10, 3-2 X_COMMON typed buffers, 2-10, 3-2, 3-4 X_OCTET typed buffers, 2-10, 3-2 XA functions and Universal Database Control, B-2 xa_close, B-2 xa_commit, B-2 xa_end, B-2 xa_open, B-2 xa_prepare, B-2 xa_recover, B-2 xa_rollback, B-2 xa_start, B-2 XATMI interface buffer management functions, 2-9, 2-13, 2-16 communications functions C Compiler, 2-13 COBOL, 2-14 JVM on OS 2200, 2-15 nonglobal transactions, B-4 service advertisement C, 2-14 COBOL, 2-15 service initialization routines COBOL, 2-15 XFR$MNQ, 7-6, 7-8 XQT parameter, MAS utility, 5-7 Z ZOOM element named with XQT parameter, MAS utility, 5-7 Special Characters @ @START statement, batch servers, 5-21 @XQT statement, batch servers, 5-21 7833 5080 009 Index 9

Index Index 10 7833 5080 009

.

2012 Unisys Corporation. All rights reserved. *78335080-009* 7833 5080 009