Compaq ACMS for OpenVMS

Writing Server Procedures

Order Number: AA--N691J--TE

December 1999

This manual describes how to write programs to use with tasks and how to debug tasks and programs. This manual also describes how Compaq ACMS for OpenVMS (ACMS) transaction processing (TP) software works with third-party database managers. It also describes how ACMS TP software works with Copmpaq's APPC/LU6.2 programming interface software to communicate with an IBM CICS application on an IBM system.

Revision/Update Information: This manual supersedes Digital ACMS for OpenVMS Writing Server Procedures, Version 4.2.

Operating System: Compaq OpenVMS Alpha Version 6.2 and above, excluding Version 7.0
Compaq OpenVMS VAX Version 6.2 and above, excluding Version 7.0

Software Version: Compaq ACMS Version 4.3 for OpenVMS

Compaq Computer Corporation
Houston, Texas

December 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq Computer Corporation or an authorized sublicensor.

Compaq, the Compaq logo, and the DIGITAL logo are registered in the U.S. Patent and Trademark Office.

ACMS, ACMS Desktop, ALL-IN-1, Alpha, AlphaServer, DATATRIEVE, DEC, DECdesign, DECdtm, DECforms, DEC FORTRAN, DECnet, DECset, DIGITAL, MicroVAX, OpenVMS, PATHWORKS, Tru64, ULTRIX, VAX, VAX C, VAX COBOL, VAX DATATRIEVE, VAX DOCUMENT, VAX FMS, VAX FORTRAN, VAX RMS, VAX SMG, VAX 9000, VMS, VMScluster, VT, VT100, VT200, and VT300 are trademarks of Compaq Computer Corporation.

The following are third-party trademarks:

Microsoft and Windows are registered trademarks of Microsoft Corporation.
IBM and CICS are a registered trademarks of International Business Machines, Inc.
Oracle is a registered trademark of Oracle Corporation.
Oracle CODASYL DBMS, Oracle CDD/Administrator, Oracle CDD/Repository, Oracle Rdb, Oracle SQL/Services, Oracle Trace, and Oracle Trace Collector are trademarks of Oracle Corporation.
SCO is a trademark of Santa Cruz Operations, Inc.
Novell and NetWare are registered trademarks of Novell, Inc.
HyperCard and Macintosh are registered trademarks of Apple Computer, Inc.
Motif and UNIX are registered trademarks of The Open Group.

ZK6607

The OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

This manual explains how to write and debug procedures for Compaq ACMS for OpenVMS (ACMS) applications. It also provides reference information for the ACMS programming services and debugger commands.

In addition, Compaq is commited to maximizing a customer's use of existing hardware and software by offering interoperable, flexible, and reliable software such as ACMS, which can interoperate with third-party database products such as Oracle, and and interconnect products such as APPC/LU6.2. In keeping with this commitment, this manual contains guidelines for integrating Compaq ACMS for OpenVMS with third-party databases such as Oracle. In addition, this manual provides guidelines for tying together Compaq ACMS for OpenVMS and IBM® systems.

Intended Audience

This document is intended for persons who will:

Write step procedures for ACMS tasks
Write ACMS initialization, termination, and cancellation procedures
Debug ACMS tasks and procedures
Integrate ACMS with a third-party database, such as Oracle
Tie ACMS together with an IBM system

To program the ACMS system, you need a beginner's knowledge of a programming language that conforms to the OpenVMS Calling Standard---VAX COBOL or VAX BASIC, for example. If you are using Oracle CODASYL DBMS or Oracle Rdb, you also need a beginner's knowledge of database programming. You do not need extensive experience with OpenVMS programming tools or system programming.

For Part 3, this manual assumes that the reader has a working knowledge of Oracle databases (especially readers who are programming-level personnel). This section does not attempt to illustrate the creation or maintenance of an Oracle database. The approach that is taken assumes that there is an existing Oracle database on the OpenVMS system. Also, the Oracle example is for illustration purposes only; is is not meant to be the definitive way to create an ACMS application that accesses an Oracle database.

For Part 4, this manual assumes that the reader has a working knowledge of LU6.2 and DECnet/SNA concepts (especially readers who are programming-level personnel). This section does not attempt to illustrate the creation or maintenance of an LU6.2 gateway between an OpenVMS system and an IBM system or a CICS® application on an IBM system. The approach that is taken in the detailed sections of the guide assumes that there is an existing CICS application on the IBM system and an existing LU6.2 gateway between the systems. Also, the LU6.2 example is for illustration purposes only; it is not meant to be the definitive way to create an ACMS application that interfaces with a CICS application.

Document Structure

This manual contains tutorial information for ACMS application programming, followed by reference information for ACMS programming tools and debugging commands, and guidelines for integrating ACMS with third-party databases and IBM systems. Following the guidelines are appendixes and an index.

Part 1 --- User Information

Chapter 1 Introduces ACMS application programming by explaining procedure server terminology, the kinds of programs you write, the ACMS tools you use to write and debug ACMS application programs, and the programming tools supplied by related products.

Chapter 2 Explains how to write initialization, termination, and cancel procedures for ACMS tasks.

Chapter 3 Presents recommendations for writing step procedures, including naming and structuring step procedures, using workspaces, handling errors in step procedures, and performing terminal I/O from a procedure server.

Chapter 4 Explains how to write procedures for tasks that use Oracle Rdb databases with SQL, Oracle Rdb with RDO, Oracle CODASYL DBMS databases, and RMS files.

Chapter 5 Explains how to create message files for ACMS task groups.

Chapter 6 Explains how to build procedure server images.

Chapter 7 Explains how to debug tasks, including tasks called by user-written agent programs, as well as procedures called by tasks.

Chapter 8 Provides guidelines to transition procedures so that they run in the ACMS run-time environment.

Part 2 --- Reference Material

Chapter 9 Provides reference material for the ACMS programming services.

Chapter 10 Provides reference material for the ACMS Task Debugger commands.

Part 3 --- Interoperability with Third-Party Databases: Oracle Case Study

Chapter 11 Describes key ACMS and Oracle interoperability concepts.

Chapter 12 Walks you through a sample application that uses ACMS in conjunction with Oracle.

Part 4 --- Interoperability with IBM LU6.2 and CICS

Chapter 13 Describes key ACMS and APPC/LU6.2 technical concepts.

Chapter 14 Walks you through a sample program that uses ACMS and APPC/LU6.2 products to interoperate with an IBM CICS system and database.

Part 5 --- Appendixes

Appendix A Describes the ACMS system workspaces.

Appendix B Lists the libraries referred to in the AVERTZ procedures that are used as examples in the manual.

Appendix C Describes superseded features.

Related Documents

Read Compaq ACMS for OpenVMS Getting Started before using this guide; this book provides an introduction to developing applications with ACMS and Compaq DECforms software. It explains the basic concepts and facilities of ACMS and other products needed for developing ACMS applications. The collection of examples in this book shows the development of a complete ACMS application and explains how to install and run the application. The following table lists the documents in the ACMS documentation set.

ACMS Information Description

Compaq ACMS Version 4.3 for OpenVMS Release Notes+ Information about the latest release of the software

Compaq ACMS Version 4.3 for OpenVMS Installation Guide Description of installation requirements, the installation procedure, and postinstallation tasks.

Compaq ACMS for OpenVMS Getting Started Overview of ACMS software and documentation.
Tutorial for developing a simple ACMS application.
Description of the AVERTZ sample application.

Compaq ACMS for OpenVMS Concepts and Design Guidelines Description of how to design an ACMS application.

Compaq ACMS for OpenVMS Writing Applications Description of how to write task, task group, application, and menu definitions using the Application Definition Utility.
Description of how to write and migrate ACMS applications on an OpenVMS Alpha system.

Compaq ACMS for OpenVMS Writing Server Procedures Description of how to write programs to use with tasks and how to debug tasks and programs. Description of how ACMS works with the APPC/LU6.2 programming interface to communicate with IBM CICS applications. Description of how ACMS works with third-party database managers, with Oracle used as an example.

Compaq ACMS for OpenVMS Systems Interface Programming Description of using Systems Interface (SI) Services to submit tasks to an ACMS system.

Compaq ACMS for OpenVMS ADU Reference Manual Reference information about the ADU commands, phrases, and clauses.

Compaq ACMS for OpenVMS Quick Reference List of ACMS syntax with brief descriptions.

Compaq ACMS for OpenVMS Managing Applications Description of authorizing, running, and managing ACMS applications, and controlling the ACMS system.

Compaq ACMS for OpenVMS Remote Systems Management Guide Description of the features of the Remote Manager for managing ACMS systems, how to use the features, and how to manage the Remote Manager.

Online help+ Online help about ACMS and its utilities.

ACMS Information	Description
Compaq ACMS Version 4.3 for OpenVMS Release Notes+	Information about the latest release of the software
Compaq ACMS Version 4.3 for OpenVMS Installation Guide	Description of installation requirements, the installation procedure, and postinstallation tasks.
Compaq ACMS for OpenVMS Getting Started	Overview of ACMS software and documentation. Tutorial for developing a simple ACMS application. Description of the AVERTZ sample application.
Compaq ACMS for OpenVMS Concepts and Design Guidelines	Description of how to design an ACMS application.
Compaq ACMS for OpenVMS Writing Applications	Description of how to write task, task group, application, and menu definitions using the Application Definition Utility. Description of how to write and migrate ACMS applications on an OpenVMS Alpha system.
Compaq ACMS for OpenVMS Writing Server Procedures	Description of how to write programs to use with tasks and how to debug tasks and programs. Description of how ACMS works with the APPC/LU6.2 programming interface to communicate with IBM CICS applications. Description of how ACMS works with third-party database managers, with Oracle used as an example.
Compaq ACMS for OpenVMS Systems Interface Programming	Description of using Systems Interface (SI) Services to submit tasks to an ACMS system.
Compaq ACMS for OpenVMS ADU Reference Manual	Reference information about the ADU commands, phrases, and clauses.
Compaq ACMS for OpenVMS Quick Reference	List of ACMS syntax with brief descriptions.
Compaq ACMS for OpenVMS Managing Applications	Description of authorizing, running, and managing ACMS applications, and controlling the ACMS system.
Compaq ACMS for OpenVMS Remote Systems Management Guide	Description of the features of the Remote Manager for managing ACMS systems, how to use the features, and how to manage the Remote Manager.
Online help+	Online help about ACMS and its utilities.

+Available on line only.

The following documentation is also useful:

DECforms Guide to Commands and Utilities
Explains how to create DECforms forms and design DECforms panels.
Oracle CDD/Repository documentation
Describes how to store record definitions in Oracle CDD/Repository.
Oracle CODASYL DBMS documentation
Explains how to use DML statements and callable DBQ in programs using an Oracle CODASYL DBMS database.
Oracle Rdb documentation
Provides Oracle Rdb language elements and statements, and provides information about using Oracle Rdb data manipulation statements in application programs.
Documentation for the SQL interface to Oracle Rdb
Describes the SQL interface to Oracle Rdb, including the statements and compiler used to write ACMS application programs.
VAX TDMS Request and Programming Manual
Provides information on Terminal Data Management System (TDMS) programming calls used in ACMS programs.
OpenVMS Debugger Manual and VMS Message Utility Manual
Describe how to use the OpenVMS Debugger and the Message Utility.
VAX COBOL User Manual and VAX COBOL Reference Manual
DEC COBOL User Manual and DEC COBOL Reference Manual
Explain the COBOL statements and compiler used to write ACMS application programs.
VAX BASIC User Manual and VAX BASIC Reference Manual
BASIC for OpenVMS Systems User's Manual and BASIC for OpenVMS Systems Reference Manual
Explain the BASIC statements and compiler used to write ACMS application programs.

For additional information on the compatibility of other software products with this version of ACMS, refer to the Compaq ACMS for OpenVMS Software Product Description (SPD 25.50.xx).

For additional information about the Open Systems Software Group (OSSG) products and services, access the following OpenVMS World Wide Web address:

http://www.compaq.com/openvms

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@compaq.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address for information about how to order additional documentation:

http://www.compaq.com/openvms

To reach the OpenVMS documentation website, click the Documentation link.

If you need help deciding which documentation best meets your needs, call 1--800--ATCOMPA.

Conventions

The following conventions are used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must press and hold the key labeled Ctrl while you press another key or a pointing device button.

PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

Monospace text Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
In the HMTL version of this document, this text style may appear as italics.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

bold text Bold text represents the introduction of a new term or the name of an argument, an attribute, or a reason.
In the HMTL version of this document, this text style may appear as italics.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE Uppercase text indicates the name of a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege.
In command format descriptions, uppercase text is an optional keyword.

UPPERCASE In command format descriptions, uppercase text that is underlined is required. You must include it in the statement if the clause is used.

lowercase In command format descriptions, a lowercase word indicates a required element.

<lowercase> In command format descriptions, lowercase text in angle brackets indicates a required clause or phrase.

( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[| |] In command format descriptions, vertical bars within square brackets indicate that you can choose any combination of the enclosed options, but you can choose each option only once.

{| |} In command format descriptions, vertical bars within braces indicate that you must choose one of the options listed, but you can use each option only once.

References to Products

The ACMS documentation set often refers to products by abbreviated names. The following product abbreviations are used in this documentation set:

Abbreviation Product

ACMS Compaq ACMS for OpenVMS Alpha, and Compaq ACMS for OpenVMS VAX

Ada DEC Ada for OpenVMS Alpha Systems, and DEC Ada for OpenVMS VAX Systems

BASIC DEC BASIC for OpenVMS, and VAX BASIC

C DEC C for OpenVMS Alpha Systems, and DEC C for OpenVMS VAX Systems

CDD Oracle CDD/Administrator, and Oracle CDD/Repository

COBOL DEC COBOL for OpenVMS Alpha Systems, and VAX COBOL for OpenVMS VAX Systems

DATATRIEVE DEC DATATRIEVE for OpenVMS Alpha, and DEC DATATRIEVE for OpenVMS VAX

DBMS Oracle CODASYL DBMS

DECforms Compaq DECforms

FORTRAN DEC Fortran for OpenVMS Alpha Systems, and DEC Fortran for OpenVMS VAX Systems

OpenVMS The Compaq OpenVMS Alpha operating system, and the Compaq OpenVMS VAX operating system

Pascal DEC Pascal, and VAX Pascal

PL/I PL/I for VAX VMS

Rdb Oracle Rdb

SQL The SQL interface to Oracle Rdb

TDMS Compaq TDMS

Abbreviation	Product
ACMS	Compaq ACMS for OpenVMS Alpha, and Compaq ACMS for OpenVMS VAX
Ada	DEC Ada for OpenVMS Alpha Systems, and DEC Ada for OpenVMS VAX Systems
BASIC	DEC BASIC for OpenVMS, and VAX BASIC
C	DEC C for OpenVMS Alpha Systems, and DEC C for OpenVMS VAX Systems
CDD	Oracle CDD/Administrator, and Oracle CDD/Repository
COBOL	DEC COBOL for OpenVMS Alpha Systems, and VAX COBOL for OpenVMS VAX Systems
DATATRIEVE	DEC DATATRIEVE for OpenVMS Alpha, and DEC DATATRIEVE for OpenVMS VAX
DBMS	Oracle CODASYL DBMS
DECforms	Compaq DECforms
FORTRAN	DEC Fortran for OpenVMS Alpha Systems, and DEC Fortran for OpenVMS VAX Systems
OpenVMS	The Compaq OpenVMS Alpha operating system, and the Compaq OpenVMS VAX operating system
Pascal	DEC Pascal, and VAX Pascal
PL/I	PL/I for VAX VMS
Rdb	Oracle Rdb
SQL	The SQL interface to Oracle Rdb
TDMS	Compaq TDMS

Contents

Index

Chapter 1	Introduces ACMS application programming by explaining procedure server terminology, the kinds of programs you write, the ACMS tools you use to write and debug ACMS application programs, and the programming tools supplied by related products.
Chapter 2	Explains how to write initialization, termination, and cancel procedures for ACMS tasks.
Chapter 3	Presents recommendations for writing step procedures, including naming and structuring step procedures, using workspaces, handling errors in step procedures, and performing terminal I/O from a procedure server.
Chapter 4	Explains how to write procedures for tasks that use Oracle Rdb databases with SQL, Oracle Rdb with RDO, Oracle CODASYL DBMS databases, and RMS files.
Chapter 5	Explains how to create message files for ACMS task groups.
Chapter 6	Explains how to build procedure server images.
Chapter 7	Explains how to debug tasks, including tasks called by user-written agent programs, as well as procedures called by tasks.
Chapter 8	Provides guidelines to transition procedures so that they run in the ACMS run-time environment.

Chapter 9	Provides reference material for the ACMS programming services.
Chapter 10	Provides reference material for the ACMS Task Debugger commands.

Chapter 11	Describes key ACMS and Oracle interoperability concepts.
Chapter 12	Walks you through a sample application that uses ACMS in conjunction with Oracle.

Chapter 13	Describes key ACMS and APPC/LU6.2 technical concepts.
Chapter 14	Walks you through a sample program that uses ACMS and APPC/LU6.2 products to interoperate with an IBM CICS system and database.

Appendix A	Describes the ACMS system workspaces.
Appendix B	Lists the libraries referred to in the AVERTZ procedures that are used as examples in the manual.
Appendix C	Describes superseded features.

Internet	openvmsdoc@compaq.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must press and hold the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
`Monospace text`	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example. In the HMTL version of this document, this text style may appear as italics.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.
bold text	Bold text represents the introduction of a new term or the name of an argument, an attribute, or a reason. In the HMTL version of this document, this text style may appear as italics.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE	Uppercase text indicates the name of a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege. In command format descriptions, uppercase text is an optional keyword.
UPPERCASE	In command format descriptions, uppercase text that is underlined is required. You must include it in the statement if the clause is used.
lowercase	In command format descriptions, a lowercase word indicates a required element.
<lowercase>	In command format descriptions, lowercase text in angle brackets indicates a required clause or phrase.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[\| \|]	In command format descriptions, vertical bars within square brackets indicate that you can choose any combination of the enclosed options, but you can choose each option only once.
{\| \|}	In command format descriptions, vertical bars within braces indicate that you must choose one of the options listed, but you can use each option only once.