|
HP OpenVMS System Services Reference Manual
June 2010
This manual describes a set of routines that the HP 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
HP OpenVMS System Services Reference Manual, Version 8.2
Software Version:
OpenVMS Version 8.4 for Integrity servers
OpenVMS Alpha Version 8.4
Hewlett-Packard Company
Palo Alto, California
© Copyright 2010 Hewlett-Packard Development Company, L.P.
Confidential computer software. Valid license from HP required for
possession, use or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
The information contained herein is subject to change without notice.
The only warranties for HP products and services are set forth in the
express warranty statements accompanying such products and services.
Nothing herein should be construed as constituting an additional
warranty. HP shall not be liable for technical or editorial errors or
omissions contained herein.
Intel and Itanium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other
countries.
Printed in the US
ZK4527
The HP OpenVMS documentation set is available on CD-ROM.
Preface
Intended Audience
This manual is intended for system and application programmers who want
to call system services.
System Services Support for HP OpenVMS Alpha and
Integrity servers 64-bit Addressing
As of Version 7.0, the HP 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 and Integrity servers
architectures available to the OpenVMS Alpha and Integrity servers
operating systems 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 HP OpenVMS Programming Concepts Manual.
The following section briefly describes how 64-bit addressing support
affects OpenVMS system services. For complete information about OpenVMS
Alpha and Integrity servers 64-bit addressing features, refer to the
HP OpenVMS Programming Concepts Manual.
64-Bit System Services Terminology
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
or Integrity servers 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.
Use of the _64
Suffix
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.
|
Sign-Extension Checking
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.
Related Documents
The HP OpenVMS Programming Concepts 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.
Application developers using XA-compliant or other resource managers
should refer to the HP OpenVMS Programming Concepts Manual.
The following documents might also be useful:
- HP OpenVMS Programming Concepts Manual
- Guide to OpenVMS File Applications
- HP OpenVMS Guide to System Security
- DECnet-Plus for OpenVMS Introduction and User's Guide
- OpenVMS Record Management Services Reference Manual
- HP OpenVMS I/O User's Reference Manual
- HP OpenVMS Guide to Upgrading Privileged-Code Applications
For additional information about HP OpenVMS products and services,
visit the following World Wide Web address:
http://www.hp.com/products/openvms
|
Reader's Comments
HP welcomes your comments on this manual. Please send comments to:
How To Order Additional Documentation
For information about how to order additional documentation, visit the
following World Wide Web address:
http://www.hp.com/go/openvms/doc/order
|
Conventions
The following conventions are 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 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.
|
( )
|
In command format descriptions, parentheses indicate that you must
enclose choices in parentheses if you specify more than one.
|
[ ]
|
In the HP 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 separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
|
{ }
|
In command format descriptions, braces indicate required choices; you
must choose at least one of the items listed. Do not type the braces on
the command line.
|
bold type
|
Bold type represents the introduction of a new term. It also represents
the name of an argument, an attribute, or a reason.
|
italic type
|
Italic type 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 TYPE
|
Uppercase type indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
|
Example
|
This typeface indicates code examples, command examples, and
interactive screen displays. In text, this type also identifies URLs,
UNIX commands and pathnames, PC-based commands and folders, and certain
elements of the C programming language.
|
-
|
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.
|
System Service Descriptions
System services provide basic operating system functions, interprocess
communication, and various control resources.
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$_BUFFEROVF, 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.
Returns
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.
$ABORT_TRANS
Ends a transaction by aborting it.
Format
SYS$ABORT_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]
,[reason] ,[bid]]
C Prototype
int sys$abort_trans (unsigned int efn, unsigned int flags, struct _iosb
*iosb,...);
Arguments
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 used.
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, described in Table SYS-1. All undefined bits must be 0. If this
argument is omitted, no flags are used.
Table SYS-1 $ABORT_TRANS Option Flags
Flag |
Description |
DDTM$M_NOWAIT
|
Set this flag to indicate that the service should return to the caller
without waiting for final cleanup. Note that $ABORT_TRANSW with the
DDTM$M_NOWAIT flag set is not equivalent to $ABORT_TRANS. $ABORT_TRANS
returns when the operation has been queued. The former does not return
until the operation has been initiated. The latter returns as soon as
the operation has been queued. The full range of status values may be
returned from a nowait call.
|
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. It may return
different reasons to different branches of the transaction. 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,
which are defined in Table SYS-2:
Table SYS-2 Abort Reason Codes
Symbolic Name |
Description |
DDTM$_ABORTED
|
The application aborted the transaction without giving a reason.
|
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$_ORPHAN_BRANCH
|
An unauthorized branch caused failure.
|
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; an authorized branch was
not added to the transaction.
|
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:
astadr
OpenVMS usage: |
ast_procedure |
type: |
procedure value |
access: |
call without stack unwinding |
mechanism: |
by reference |
AST routine that is executed when the service completes, if SS$_NORMAL
is returned in R0. The astadr argument is the address
of the entry mask of this routine. The routine is executed in the
access mode of the caller.
astprm
OpenVMS usage: |
user_arg |
type: |
longword (unsigned) |
access: |
read only |
mechanism: |
by value |
AST parameter that is passed to the AST routine specified by the
astadr argument.
tid
OpenVMS usage: |
trans_id |
type: |
octaword (unsigned) |
access: |
read only |
mechanism: |
by reference |
Identifier of the transaction to be aborted.
If this argument is omitted, $ABORT_TRANS aborts the default
transaction of the calling process.
reason
OpenVMS usage: |
cond_value |
type: |
longword (unsigned) |
access: |
read only |
mechanism: |
by value |
Code that gives the reason why the application is aborting the
transaction. The $DDTMMSGDEF macro defines symbolic names for abort
reason codes. The codes currently defined are listed in Table SYS-2.
The default value for this argument is DDTM$_ABORTED.
bid
OpenVMS usage: |
branch_id |
type: |
octaword (unsigned) |
access: |
read only |
mechanism: |
by reference |
The identifier (BID) of the branch that is aborting the transaction.
The default value of this argument is zero, which is the BID of the
branch that started the transaction.
Description
The Abort Transaction service ends a transaction by aborting it.
The $ABORT_TRANS system service:
- Initiates abort processing for the specified transaction, if it has
not already been initiated.
If abort processing has not already
been initiated, the DECdtm transaction manager instructs the resource
managers to abort (roll back) the transaction operations so that none
of those operations ever take effect. It delivers an abort event to
each RM participant in the transaction that is associated with an RMI
that requested abort events.
- Removes the specified branch from the specified transaction in this
process.
Preconditions for the successful completion of $ABORT_TRANS include:
- If the BID is zero, the calling process must have started the
transaction.
- If the BID is nonzero, the calling process must contain the
specified branch of the specified transaction.
- If the BID is nonzero, the tid argument must not
be omitted. If you explicitly pass the BID, you must also explicitly
pass the TID.
$ABORT_TRANS may fail for various reasons, including:
- The preconditions were not met.
- There has already been a call to $ABORT_TRANS, $END_TRANS, or
$END_BRANCH for the specified branch.
Postconditions on successful completion of $ABORT_TRANS are listed in
Table SYS-3:
Table SYS-3 Postconditions When$ABORT_TRANS Completes Successfully
Postcondition |
Meaning |
The transaction is ended.
|
If DDTM$M_NOWAIT is clear:
- The TID of the transaction is invalid; calls to any DECdtm system
services except $GETDTI and $SETDTI that pass the TID will fail, and
calls to resource managers that pass the TID will fail.
- The transaction no longer has any application or RM participants on
the local node.
- All communications about the transaction between the local DECdtm
transaction manager and other DECdtm transaction managers are finished
(including the final "cleanup" acknowledgment).
|
The outcome of the transaction is abort.
|
None of the operations of the transaction will ever take effect.
|
DECdtm quotas are returned.
|
If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by
calls on the local node to DECdtm services are now returned.
|
The transaction is not the default transaction of the calling process.
|
If DDTM$M_NOWAIT is clear, then, if the transaction was the default
transaction of the calling process, it is now no longer the default.
|
$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) until all branches on the local node have
been removed from the transaction. Thus this call to $ABORT_TRANS
cannot complete successfully until every authorized and synchronized
branch on the local node has initiated a call to $END_TRANS,
$END_BRANCH, or $ABORT_TRANS.
$ABORT_TRANS must deliver notification ASTs to resource managers
participating in the transaction. Therefore it will not complete
successfully while the calling process is either:
- In an access mode that is more privileged than the DECdtm calls
made by any resource manager participating 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 the same access mode as the least privileged DECdtm
calls made by any resource manager participating in the transaction.
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.
Note that successful completion of $ABORT_TRANS is not indefinitely
postponed by network failure.
Required Access or Privileges
None
Required Quotas
ASTLM
Related Services
$ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID,
$DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS,
$END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,
$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW,
$SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW,
$START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW
Condition Values Returned
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 or the
tid argument was omitted and the
bid argument was not zero.
|
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
|
A required argument was missing.
|
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$_NOSUCHBID
|
The calling process did not contain the branch identified by the BID
passed in the
bid argument (possibly because there has already been
a call to $ABORT_TRANS, $END_TRANS, or $END_BRANCH for that branch).
This error is returned only if the
bid argument is not zero.
|
SS$_NOSUCHTID
|
A transaction with the specified transaction identifier does not exist.
|
SS$_NOTORIGIN
|
A
bid of zero was specified and the calling process did
not start the transaction.
|
SS$_TPDISABLED
|
The TP_SERVER process was not running on the local node.
|
SS$_WRONGSTATE
|
Commit processing for the transaction had already started. This can
occur if
bid is zero or the specified branch was unsynchronized.
|
|