Order Number: AA--EA12H--TE

This manual describes how to use Systems Interface (SI) programming services to submit tasks to a Compaq ACMS for OpenVMS system.

Revision/Update Information: This manual supersedes the Digital ACMS for OpenVMS Systems Interface Programming, Version 4.2.

Operating System: Compaq OpenVMS Alpha Version 6.2 or higher, excluding Version 7.0
Compaq OpenVMS VAX Version 6.2 or higher, excluding Version 7.0

Software Version: Compaq ACMS Version 4.3 for OpenVMS

Compaq Computer Corporation Houston, Texas

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.

© 1999 Compaq Computer Corporation

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:

IBM is a registered trademark 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.

Other product names mentioned herein may be the trademarks of their respective companies.

ZK6606

The OpenVMS documentation set is available on CD-ROM.

Contents

Index

The ACMS Systems Interface (SI) is a group of system services that enable a programmer to interface a wide range of external devices and systems with the Compaq ACMS for OpenVMS (ACMS) run-time environment. For example, you can provide a new method of menu selection or an alternate terminal management system to replace or supplement the default ACMS menu system.

This manual introduces the concept of the ACMS agent program, a program that invokes a task that executes in an ACMS application. This manual clarifies and complements information you gain by first reading the manuals in the Planning and Design as well as the Development and Testing phases of the documentation life cycle.

Intended Audience

Read this manual if you need a detailed description of and reference information about the ACMS Systems Interface, referred to in this document as the SI. This manual is for systems programmers, experienced users, or application designers with a strong knowledge of ACMS, the Compaq OpenVMS operating system, and programming on the OpenVMS operating system.

Document Structure

This manual contains overview information, reference information for calling the SI services, and examples of agent programs.

Chapter 1	Introduces the SI services, gives a brief description of each, and describes the function of agent programs.
Chapter 2	Explains the features common to all the SI services and the features common to the various languages that can call the services.
Chapter 3	Explains the specific SI services that agent programs need to call to start and end a distributed transaction and to access data on remote nodes.
Chapter 4	Describes the initialization services and exchange I/O services, and gives reference information for calling them in agent programs.
Chapter 5	Describes the submitter services and gives reference information for calling them in agent programs.
Chapter 6	Describes the stream services and gives reference information for calling them in agent programs.
Chapter 7	Provides a number of agent program examples.
Appendix A	Describes superseded exchange I/O and stream services.

Related Documents

The following table lists the books in the Compaq ACMS for OpenVMS 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.

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

ACMS Help

ACMS and its components provide the following online help:

• DCL-level help
  Enter HELP ACMS at the DCL prompt for complete help about the ACMS command and qualifiers, and for other elements of ACMS for which independent help systems do not exist. DCL-level help also provides brief help messages for elements of ACMS that contain independent help systems (such as the ACMS utilities) and for related products used by ACMS (such as DECforms).
• ACMS utilities help
  Each of the following ACMS utilities has an online help system:

  ACMS Debugger
  ACMSGEN Utility
  ACMS Queue Manager (ACMSQUEMGR)
  Application Definition Utility (ADU)
  Application Authorization Utility (AAU)
  Device Definition Utility (DDU)
  User Definition Utility (UDU)
  Audit Trail Report Utility (ATR)
  Software Event Log Utility Program (SWLUP)

  
  The two ways to get utility-specific help are:
  • Run the utility and type HELP at the utility prompt.
  • Use the DCL HELP command. At the "Topic?" prompt, type @ followed by the name of the utility. Use the ACMS prefix, even if the utility does not have an ACMS prefix (except for SWLUP). For example:

    Topic? @ACMSQUEMGR Topic? @ACMSADU

    
    However, do not use the ACMS prefix with SWLUP:

    Topic? @SWLUP

  
  Note that if you run the ACMS Debugger Utility and then type HELP, you must specify a file. If you ask for help from the DCL level with @, you do not need to specify a file.

• ACMSPARAM.COM and ACMEXCPAR.COM help
  Help for the command procedures that set parameters and quotas is a subset of the DCL-level help. You have access to this help from the DCL prompt, or from within the command procedures.
• LSE help
  ACMS provides ACMS-specific help within the LSE templates that assist in the creation of applications, tasks, task groups, and menus. The ACMS-specific LSE help is a subset of the ADU help system. Within the LSE templates, this help is context-sensitive. Type HELP/IND (PF1-PF2) at any placeholder for which you want help.
• Error help
  ACMS and each of its utilities provide error message help. Use HELP ACMS ERRORS from the DCL prompt for ACMS error message help. Use HELP ERRORS from the individual utility prompts for error message help for that utility.
• Terminal user help
  At each menu within an ACMS application, ACMS provides help about terminal user commands, special key mappings, and general information about menus and how to select tasks from menus.
• Forms help
  For complete help for DECforms or TDMS, use the help systems for these products.

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 to which this manual belongs often refers to certain products by abbreviated names:

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