OpenVMS System Services Reference Manual

OpenVMS System Services Reference Manual

November 1996

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 for OpenVMS Alpha Version 7.0 and OpenVMS VAX Version 7.0.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment 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 Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Digital Equipment Corporation: Bookreader, DEC Fortran, DECchip, DECdns, DECdtn, DECnet, DECnet/OSI, DECwindows, Digital, HSC, MASSBUS, MicroVAX, MicroVAX II, MSCP, OpenVMS, OpenVMS Cluster, RA, StorageWorks, TA, TMSCP, TURBOchannel, ULTRIX, VAX, VAX C, VAX DOCUMENT, VAX MACRO, VAX-11/780, VAXcluster, VAXft, VAXstation, VMS, VMScluster, VT, and the DIGITAL logo.

The following are third-party trademarks:

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

All other trademarks and registered trademarks are the property of their respective holders.

ZK4527

The 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 OpenVMS Alpha 64-bit Addressing

As of Version 7.0, the OpenVMS Alpha operating system provides support for 64-bit virtual memory addresses, which 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, see the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.

64-Bit System Services Terminology

32-Bit System Service
A 32-bit system service is a system service that 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 is an interface that 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 a system service that is defined to accept all address arguments as 64-bit addresses (not necessarily 32-bit sign-extended values). Also, a 64-bit system service 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 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

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 will receive sign-extension checking. Any argument passed to these services that is not properly sign-extended will cause the error status SS$_ARG_GTR_32_BITS to be returned.

Reader's Comments

Digital 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, ZKO3-4/U08

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

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synony with OpenVMS Alpha or Alpha.

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.

... 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 format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.

[ ] In format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification, or in the syntax of a substring specification in an assignment statement.)

{ } In format descriptions, braces surround a required choice of options; you must choose one of the options listed.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

italic text Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER= name), and command parameters in text.

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

- A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows.

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 to VMS users. This document provides the reference material needed by users to call system services.

Condition values returned by system services may provide information; that is, they do not indicate only whether the service completed successfully. The usual condition value indicating success is SS$_NORMAL, but others are 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. This condition value gives the program 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]]

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 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.

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 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: transaction_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. Those currently defined are shown in Table SYS-1. The default value for this argument is DDTM$_ABORTED.

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.

**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.

DESCRIPTION

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.

Required Access or Privileges

None

Required Quotas

ASTLM

Related Services

$ABORT_TRANSW, $END_TRANS, $END_TRANSW, $START_TRANS, $START_TRANSW

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.

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.

$ABORT_TRANSW

Ends a transaction by aborting it.
$ABORT_TRANSW always waits for the request to complete before returning to the caller. Other than this, it is identical to $ABORT_TRANS.
Do not call $ABORT_TRANSW from AST level, or from an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction. If you do, the $ABORT_TRANSW service will wait indefinitely.

Format

SYS$ABORT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid] ,[reason]]

C Prototype

int sys$abort_transw (unsigned int efn, struct _iosb *iosb,...);

$ADD_HOLDER

Adds a specified holder record to a target identifier.

Format

SYS$ADD_HOLDER id ,holder ,[attrib]

C Prototype

int sys$add_holder (unsigned int id, struct _generic_64 *holder, unsigned int attrib);

ARGUMENTS

id

OpenVMS usage: rights_id

type: longword (unsigned)

access: read only

mechanism: by value

Target identifier granted to the specified holder when $ADD_HOLDER completes execution. The id argument is a longword containing the binary value of the target identifier.
holder

OpenVMS usage: rights_holder

type: quadword (unsigned)

access: read only

mechanism: by reference

Holder identifier that is granted access to the target identifier when $ADD_HOLDER completes execution. The holder argument is the address of a quadword data structure that consists of a longword containing the holder's UIC identifier followed by a longword containing a value of 0.
attrib

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Attributes to be placed in the holder record when $ADD_HOLDER completes execution. The attrib argument is a longword containing a bit mask specifying the attributes. A holder is granted a specified attribute only if the target identifier has the attribute.
Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The symbols are defined in the system macro library ($KGBDEF). The symbolic name for each bit position is listed in the following table.

Bit Position Meaning When Set

KGB$V_DYNAMIC Allows holders of the identifier to remove it from or add it to the process rights database by using the DCL command SET RIGHTS_LIST.

KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves.

KGB$V_NAME_HIDDEN Allows holders of an identifier to have it translated---either from binary to ASCII or vice versa---but prevents unauthorized users from translating the identifier.

KGB$V_NOACCESS Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.

KGB$V_RESOURCE Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.

KGB$V_SUBSYSTEM Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights database by using the DCL command SET RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN	Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves.
KGB$V_NAME_HIDDEN	Allows holders of an identifier to have it translated---either from binary to ASCII or vice versa---but prevents unauthorized users from translating the identifier.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

DESCRIPTION

The Add Holder Record to Rights Database service registers the specified user as a holder of the specified identifier with the rights database.
Required Access or Privileges

Write access to the rights database is required.
Required Quota

None
Related Services

Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P.HTM
  OSSG Documentation
  22-NOV-1996 12:58:38.74
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	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 hold down the key labeled Ctrl while you press another key or a pointing device button.
...	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 format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	In format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification, or in the syntax of a substring specification in an assignment statement.)
{ }	In format descriptions, braces surround a required choice of options; you must choose one of the options listed.
`text style`	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
italic text	Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER= name), and command parameters in text.
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
-	A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows.
numbers	All numbers in text are assumed to be decimal, unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

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

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	read only
mechanism:	by value

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.

OpenVMS usage:	rights_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	rights_holder
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS System Services Reference Manual

November 1996

Contents

Preface

Intended Audience

System Services Support for OpenVMS Alpha 64-bit Addressing

64-Bit System Services Terminology

32-Bit System Service

64-Bit Friendly Interface

64-Bit System Service

Sign-Extension Checking

Related Documents

Reader's Comments

How To Order Additional Documentation

Conventions

System Service Descriptions

Returns

$ABORT_TRANS

Format

SYS$ABORT_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid] ,[reason]]

C Prototype

int sys$abort_trans (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);

ARGUMENTS

efn

flags

iosb

astadr

astprm

tid

reason

DESCRIPTION

Condition Values Returned

$ABORT_TRANSW

Format

SYS$ABORT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid] ,[reason]]

C Prototype

int sys$abort_transw (unsigned int efn, struct _iosb *iosb,...);

$ADD_HOLDER

Format

SYS$ADD_HOLDER id ,holder ,[attrib]

C Prototype

int sys$add_holder (unsigned int id, struct _generic_64 *holder, unsigned int attrib);

ARGUMENTS

id

holder

attrib

DESCRIPTION