Updated: 11 December 1998 |
This manual describes a set of routines that the OpenVMS operating system uses to control resources, to allow process communication, to control I/O, and to perform other such operating system functions.
Revision/Update Information: This manual supersedes the OpenVMS System Services Reference Manual, Version 7.1.
Software Version: OpenVMS Alpha Version 7.2 OpenVMS VAX Version 7.2
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 or an authorized sublicensor.
Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.
© Compaq Computer Corporation 1999. All rights reserved.
The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, CDA, CI, DDIF, DEC, DECdirect, DECdtm, DECnet, DECprint, DECspell, DECterm, DECUS, DECwrite, DECwriter Correspondent, DEQNA, DIGITAL, DTIF, EDT, GIGI, HSC, LA, LiveLink, LN03, MicroVAX, MSCP, OpenVMS, PATHWORKS, PrintServer, Q-bus, RC25, ReGIS, RQDX3, RRD42, RRD50, RX01, RX02, RX33, RX50, RZ, TE16, TMSCP, TS11, ULTRIX, UNIBUS, VAX, VAX 8530, VAX 8550, VAX 11/780, VAX COBOL, VAX DOCUMENT, VAX FORTRAN, VAXft, VAXserver, VAXstation, VMS, VT, VT100, VT300, WPS, XUI, and the Compaq logo.
The following are third-party trademarks:
Adobe, Display POSTSCRIPT, and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.
Motif, OSF, OSF1, and OSF/Motif are registered trademarks, and Open Software Foundation is a trademark of the Open Software Foundation, Inc.
Oracle is a registered trademark, and Oracle CODASYL DBMS and Oracle Rdb are trademarks of Oracle Corporation.
OSI is a registered trademark of CA Management, Inc.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.
All other trademarks and registered trademarks are the property of their respective holders.
ZK4527
The OpenVMS documentation set is available on CD-ROM.
Contents | Index |
This manual is intended for system and application programmers who want to call system services.
As of Version 7.0, the OpenVMS Alpha operating system provides support for 64-bit virtual memory addresses. This support makes the 64-bit virtual address space defined by the Alpha architecture available to the OpenVMS Alpha operating system and to application programs. In the 64-bit virtual address space, both process-private and system virtual address space extend beyond 2 GB. By using 64-bit address features, programmers can create images that map and access data beyond the previous limits of 32-bit virtual addresses.
New OpenVMS system services are available, and many existing services have been enhanced to manage 64-bit address space. The system services descriptions in this manual indicate the services that accept 64-bit addresses. A list of the OpenVMS system services that accept 64-bit addresses is available in the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.
The following section briefly describes how 64-bit addressing support affects OpenVMS system services. For complete information about OpenVMS Alpha 64-bit addressing features, refer to the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.
32-Bit System Service
A 32-bit system service only supports 32-bit addresses on any of its arguments that specify addresses. If passed by value on OpenVMS Alpha, a 32-bit virtual address is actually a 64-bit address that is sign-extended from 32 bits.64-Bit Friendly Interface
A 64-bit friendly interface can be called with all 64-bit addresses. A 32-bit system service interface is 64-bit friendly if, without a change in the interface, it needs no modification to handle 64-bit addresses. The internal code that implements the system service might need modification, but the system service interface will not.64-Bit System Service
A 64-bit system service is defined to accept all address arguments as 64-bit addresses (not necessarily 32-bit sign-extended values). A 64-bit system service also uses the entire 64 bits of all virtual addresses passed to it.
The 64-bit system services include the _64 suffix for services that accept 64-bit addresses by reference. For promoted services, this suffix distinguishes the 64-bit capable version from its 32-bit counterpart. For new services, it is a visible reminder that a 64-bit-wide address cell will be read/written. |
The OpenVMS system services that do not support 64-bit addresses and all user-written system services that are not explicitly enhanced to accept 64-bit addresses receive sign-extension checking. Any argument passed to these services that is not properly sign-extended causes the error status SS$_ARG_GTR_32_BITS to be returned.
The OpenVMS Programming Interfaces: Calling a System Routine manual contains useful information for anyone who wants to call system services.
High-level language programmers can find additional information about calling system services in the language reference manual and language user's guide provided with the OpenVMS language.
The following documents might also be useful:
For a complete list and description of the manuals in the OpenVMS document set, refer to the Overview of OpenVMS Documentation.
For additional information about the Open Systems Software Group (OSSG) products and services, access the OpenVMS World Wide Web address:
http://www.openvms.digital.com |
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@zko.mts.dec.com |
Fax | 603 881-0120, Attention: OSSG Documentation, ZK03-4/U08 |
Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698 |
Use the following World Wide Web address to order additional documentation:
http://www.openvms.digital.com:81/ |
If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).
In this manual, any reference to OpenVMS is synonymous with DIGITAL OpenVMS.
VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.
In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.
The following conventions are also used in this manual:
Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down 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 indicate one of the following
possibilities:
|
.
. . |
A vertical ellipsis indicate 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. |
( ) | In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one. |
[ ] | In the OpenVMS System Services Reference Manual, brackets generally indicate default arguments. If an argument is optional, it is specified as such in the argument text. |
[|] | In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options. |
{ } | In command format descriptions, braces indicate required elements; you must choose one of the options listed. |
bold text | This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. |
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 TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
Monospace text |
Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type 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. |
- | 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. |
Condition values returned by system services not only indicate whether the service completed successfully, but can also provide other information. While the usual condition value indicating success is SS$_NORMAL, other values are also defined. For example, the condition value SS$_BUFFEROVERF, which is returned when a character string returned by a service is longer than the buffer provided to receive it, is a success code, but it also provides additional information.
Warning returns and some error returns indicate that the service may have performed some, but not all, of the requested function.
The particular condition values that each service can return are described in the Condition Values Returned section of each individual service description.
OpenVMS usage:
type: access: mechanism: |
cond_value
longword (unsigned) write only by value |
Longword condition value. All system services (except $EXIT) return by immediate value a condition value in R0.
Ends a transaction by aborting it.
SYS$ABORT_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid] ,[reason]]
int sys$abort_trans (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);
efn
OpenVMS usage: ef_number type: longword (unsigned) access: read only mechanism: by value
Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is set.flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
Flags specifying options for the service. The flags argument is a longword bit mask in which each bit corresponds to an option flag. The $DDTMDEF macro defines symbolic names for these option flags. All undefined bits must be 0. If this argument is omitted, no flags are set.DDTM$M_SYNC, the only flag currently defined, is described in the following table.
Flag Description DDTM$M_SYNC Set this flag to specify that successful synchronous completion is to be indicated by returning SS$_SYNCH. When SS$_SYNCH is returned, the AST routine is not called, the event flag is not set, and the I/O status block is not filled in. iosb
OpenVMS usage: io_status_block type: quadword (unsigned) access: write only mechanism: by reference
I/O status block in which the following information is returned:
- The completion status of the service, returned as a condition value. See the Condition Values Returned section.
- An abort reason code that gives one reason why the transaction aborted, if the completion status of the service is SS$_NORMAL.
Note that, if there are multiple reasons why the transaction aborted, the abort reason code returned in the I/O status block might not be the same as the abort reason code passed in the reason argument. The DECdtm transaction manager returns one of the reasons in the I/O status block.
For example, if the call to $ABORT_TRANS gives DDTM$_ABORTED as the reason and the transaction timeout expires at about the same time as the call to $ABORT_TRANS, then either the DDTM$_TIMEOUT or DDTM$_ABORTED reason code can be returned in the I/O status block.The $DDTMMSGDEF macro defines symbolic names for abort reason codes. Those currently defined are shown in Table SYS-1.
Table SYS-1 Abort Reason Codes Symbolic Name Description DDTM$_ABORTED The application aborted the transaction. DDTM$_COMM_FAIL A communications link failed. DDTM$_INTEGRITY A resource manager integrity constraint check failed. DDTM$_LOG_FAIL A write operation to the transaction log failed. DDTM$_PART_SERIAL A resource manager serialization check failed. DDTM$_PART_TIMEOUT The timeout specified by a resource manager expired. DDTM$_SEG_FAIL A process or image terminated. DDTM$_SERIALIZATION A DECdtm transaction manager serialization check failed. DDTM$_SYNC_FAIL The transaction was not globally synchronized. DDTM$_TIMEOUT The timeout specified on $START_TRANS expired. DDTM$_UNKNOWN The reason is unknown. DDTM$_VETOED A resource manager was unable to commit the transaction. The following diagram shows the structure of the I/O status block.
OpenVMS usage: | ast_procedure |
type: | procedure value |
access: | call without stack unwinding |
mechanism: | by reference |
OpenVMS usage: | user_arg |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
OpenVMS usage: | transaction_id |
type: | octaword (unsigned) |
access: | read only |
mechanism: | by reference |
If this argument is omitted, $ABORT_TRANS aborts the default transaction of the calling process.
OpenVMS usage: | cond_value |
type: | longword (unsigned) |
access: | read only |
mechanism: | by value |
The Abort Transaction service ends a transaction by aborting it. The DECdtm transaction manager instructs all the resource managers participating in the transaction to abort the transaction operations so that none of those operations ever takes any effect.$ABORT_TRANS must be called from the process that started the transaction.
$ABORT_TRANS does not complete successfully until all quotas allocated for the transaction by calls on the local node to DECdtm services have been returned.
$ABORT_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) while the calling process is either:
- In an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction.
RMS journaling calls DECdtm in executive mode. Oracle Rdb and Oracle CODASYL DBMS call DECdtm in user mode.- At AST level (in any access mode).
For example, if Oracle Rdb is a participant in the transaction, $ABORT_TRANS will not complete successfully while the calling process is in supervisor, executive, or kernel mode, or while the calling process is at AST level.
None
ASTLM
$ABORT_TRANSW, $END_TRANS, $END_TRANSW, $START_TRANS, $START_TRANSW
SS$_NORMAL If this was returned in R0, the request was successfully queued. If it was returned in the I/O status block, the service completed successfully. SS$_SYNCH The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set). SS$_ACCVIO An argument was not accessible by the caller. SS$_BADPARAM The options flags were invalid. SS$_BADREASON The abort reason code was invalid. SS$_CURTIDCHANGE The tid argument was omitted and a call to change the default transaction of the calling process was in progress. SS$_EXASTLM The process AST limit (ASTLM) was exceeded. SS$_ILLEFC The event flag number was invalid. SS$_INSFARGS Not enough arguments were supplied. SS$_INSFMEM There was insufficient system dynamic memory for the operation. SS$_NOCURTID An attempt was made to abort the default transaction (the tid argument was omitted) but the calling process did not have a default transaction. SS$_NOLOG The local node did not have a transaction log. SS$_NOSUCHTID A transaction with the specified transaction identifier does not exist. SS$_NOTORIGIN The calling process did not start the transaction. SS$_TPDISABLED The TP_SERVER process was not running on the local node. SS$_WRONGSTATE The calling process had already called either $ABORT_TRANS or $END_TRANS to end the transaction, and processing had not completed.
Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4527PRO.HTML
|