OpenVMS System Services Reference Manual

Document revision date: 15 July 2002

OpenVMS System Services Reference Manual

Contents

Index

(The way to invoke a resource manager operation is defined by the interfaces provided by the resource manager; refer to the resource manager documentation.)

A synchronized branch is removed from the transaction by calling $END_BRANCH, specifying the appropriate BID and TID. An unsynchronized branch is removed from the transaction by DECdtm during commit or abort processing.

The branch is also removed from the transaction (and the transaction aborted):

On termination of the current image or process.
On successful completion of a call to $ABORT_TRANS in the calling process that passes the appropriate TID and BID.

There is also a wait form of the service, $START_BRANCHW.

Required Privileges

None

Required Quotas

BYTLM, ASTLM

Related Services

$ABORT_TRANS, $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_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL If returned in R0, the request was successfully queued. If 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 to the caller.

SS$_ALRCURTID Either:

An attempt was made to make the transaction specified by the tid argument the default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process had an unended default transaction.
The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process was in progress.

SS$_BADPARAM Either the options flags were invalid or the tid argument was omitted but the bid argument was not zero.

SS$_BRANCHSTARTED There has already been a call to $START_BRANCH on the local node specifying that TID and BID (returned only if the node specified by the tm_name argument was the local node).

SS$_CONNECFAIL The node specified by the tm_name argument was not the local node, and there was no communications link between the DECdtm transaction managers on the local node and the specified node.

SS$_EXASTLM The process AST limit (ASTLM) was exceeded.

SS$_EXQUOTA The job buffered I/O byte limit quota (BYTLM) 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$_INVBUFLEN The string passed in the tx_class argument was longer than 31 characters, or the string passed in the tm_name argument was longer than 256 characters.

SS$_NOLOG The local node did not have a transaction log.

SS$_NOSUCHBID Either:

The specified BID was not returned by any call to $ADD_BRANCH or $JOIN_RM on the local node (returned only if the node specified by the tm_name argument was the local node).
An BID of zero was supplied.

SS$_NOSUCHTID The local node did not have any branches in the specified transaction (returned only if the node specified by the tm_name argument was the local node).

SS$_TPDISABLED The TP_SERVER process was not running on the local node.

SS$_WRONGSTATE The transaction was in the wrong state for the attempted operation because either:

An abort event has occurred for the transaction.
A call to $END_TRANS to end the transaction is in progress and it is now too late to add a new branch to the transaction.

$START_BRANCHW

Adds a new branch to a transaction.
$START_BRANCHW always waits for the request to complete before returning to the caller. Other than this, it is identical to $START_BRANCH.

Format

SYS$START_BRANCHW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,tm_name ,bid [,[timout] ,[acmode], [tx_class]]

C Prototype

int sys$start_branchw (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid [4], void *tm_name, unsigned int bid [4],...);

$START_TRANS

Starts a new transaction.

Format

SYS$START_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid] ,[timout] ,[acmode] ,[tx_class]]

C Prototype

int sys$start_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, which are described in Table SYS-57. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-57 $START_TRANS Option Flags
Flag Description

DDTM$M_NONDEFAULT Set this flag if you do not want the new transaction to be the default transaction of the calling process. An error is returned if this flag is set and the tid argument is zero or omitted.
If this flag is clear, the new transaction becomes the default transaction of the calling process. An error is returned if this flag is clear and the calling process already has a default transaction.

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 completion status of the service is returned as a condition value. See the Condition Values Returned section.
The following diagram shows the structure of the I/O status block:

**Table SYS-57 $START_TRANS Option Flags**
Flag	Description
DDTM$M_NONDEFAULT	Set this flag if you do not want the new transaction to be the default transaction of the calling process. An error is returned if this flag is set and the tid argument is zero or omitted. If this flag is clear, the new transaction becomes the default transaction of the calling process. An error is returned if this flag is clear and the calling process already has a default transaction.
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.

astadr

OpenVMS usage:	ast_procedure
type:	procedure entry mask
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. This routine is executed in the same access mode of the caller of the $START_TRANS service.

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:	write only
mechanism:	by reference

Address of an octaword in which the service returns the identifier (TID) of the new transaction.

No other call to $START_TRANS on any node ever returns the same TID value.

The default value of this argument is zero. An error is returned if the DDTM$M_NONDEFAULT flag is set and this argument is either omitted or zero.

timout

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

Timeout for the new transaction. This is the time at which the DECdtm transaction manager is to abort the transaction if the transaction has not already committed.

A positive time value specifies an absolute time. The absolute value of a negative time specifies an offset (delta time) from the current time.

The transaction is aborted at the next timer interval if you specify either a zero time value or any time in the past. If this argument is omitted, the new transaction has no timeout.

acmode

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

An access mode of the new branch of the new transaction.

An access mode is maintained for each transaction per process. All branches in a transaction in a process have the same access mode. Subsequent operations do not alter it. The access mode of a branch is the least privileged mode in which a successful call to $END_TRANS may be made.

Note that the transaction may be aborted by a call to $ABORT_TRANS from any access mode.

The access mode of the branch is the least privileged of the following:

The access mode of the caller
The access mode specified by the acmode argument

If the acmode argument is omitted, the access mode of the new branch is the same as that of the caller.

tx_class

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

A string that specifies the transaction class for the new transaction on the local node. This string is passed in the event reports delivered to RMIs and RM participants on the local node.

This string must be no longer than 31 characters. If this argument is omitted or the string is of length zero, the new transaction has no transaction class on the local node. In this case, the class of the transaction on the local node can be specified by a subsequent call to $START_BRANCH on that node.

Description

The $START_TRANS system service starts a new transaction whose commit or abort processing is to be coordinated by the local DECdtm transaction manager. The service:

Adds a branch running in the calling process to the new transaction. The identifier (BID) of the new branch is 0.
Sets the default transaction of the calling process to the new transaction, if the DDTM$M_NONDEFAULT flag is clear and the process does not have a default transaction.
Delivers an event of type Transaction Started to each RMI in the calling process that requested Transaction Started events and has an access mode that is the same as or more privileged than that specified in this call to $START_TRANS. See the description of the acmode argument.

The event delivered to all such RMIs is either a default transaction-started event or a nondefault transaction-started event, depending on whether the DDTM$M_NONDEFAULT flag is clear or not.
Preconditions for the successful completion of $START_TRANS are:

The local node must have a DECdtm transaction log.
The TP_SERVER process must be running on the local node.
If the DDTM$M_NONDEFAULT flag is clear, the calling process must not have an unended default transaction.

$START_TRANS may fail for various reasons including:

Preconditions were not met.
The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process is in progress.

When $START_TRANS completes successfully:

A new transaction has started, with a unique identifier.
The transaction has a single branch, with a BID of 0.
All Transaction Started events reported to RMIs in the calling process have been acknowledged.
If the DDTM$M_NONDEFAULT flag was clear, the transaction is the default transaction of the calling process.

A branch may:

Invoke resource manager operations, explicity passing the TID.
Invoke resource manager operations without specifying the TID, if the transaction is the default transaction of the calling process, and the resource manager supports default transactions.
Call $ADD_BRANCH to authorize another branch to be added to the transaction.

(The way to invoke a resource manager operation is defined by the interfaces provided by the resource manager. Refer to the resource manager documentation for additional information.)
DECdtm cannot commit the transaction until the process calls $END_TRANS.
The transaction is aborted:

On termination of the current image or process.
On successful completion of a call to $ABORT_TRANS in the calling process, specifying a BID of 0.

There is also a wait form of the service, $START_TRANSW.
Required Access or Privileges

None
Required Quotas

ASTLM, BYTLM
Related Services

$ABORT_TRANS, $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_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL If returned in R0, the request was successfully queued. If 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 to the caller.

SS$_ALCURTID Either:

An attempt was made to start a default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process had an unended default transaction.
The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process was in progress.

SS$_BADPARAM Either the DDTM$M_NONDEFAULT flag was set and the tid argument was omitted, or the options flags were invalid.

SS$_CURTIDCHANGE The DDTM$M_NONDEFAULT flag was clear 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$_EXQUOTA The job buffered I/O byte limit quota (BYTLM) 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$_INVBUFLEN The string passed to the tx_class argument was longer than 31 characters.

SS$_NOLOG The local node did not have a transaction log.

SS$_TPDISABLED The TP_SERVER process was not running on the local node.

$START_TRANSW

Starts a new transaction.
$START_TRANSW always waits for the request to complete before returning to the caller. Other than this, it is identical to $START_TRANS.

Format

SYS$START_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid] ,[timout] ,[acmode]]

C Prototype

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

$STOP_ALIGN_FAULT_REPORT (Alpha Only)

On Alpha systems, disables user image alignment fault reporting.

Format

SYS$STOP_ALIGN_FAULT_REPORT

C Prototype

int sys$stop_align_fault_report (void);

Arguments

None.

Description

The Stop Alignment Fault Reporting service disables user image alignment fault reporting.
The service returns SS$_AFR_NOT_ENABLED if user image alignment fault reporting is not enabled; otherwise, it returns success.
Required Access or Privileges

None
Required Quota

None
Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_AFR_NOT_ENABLED The $START_ALIGN_FAULT_REPORT service has not been called.

$STOP_SYS_ALIGN_FAULT_REPORT (Alpha Only)

On Alpha systems, disables systemwide alignment fault reporting.

Format

SYS$STOP_SYS_ALIGN_FAULT_REPORT

C Prototype

int sys$stop_sys_align_fault_report (void);

Arguments

None.

Description

The Stop System Alignment Fault Reporting service disables systemwide alignment fault reporting.
The service returns SS$_AFR_NOT_ENABLED if systemwide alignment fault reporting is not enabled; otherwise, it returns success.
Required Access or Privileges

CMKRNL privilege is required.
Required Quota

None
Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_NOPRIV The caller lacks sufficient privilege.

SS$_AFR_NOT_ENABLED The $START_ALIGN_FAULT_REPORT service has not been called.

$SUBSYSTEM

Saves or restores the process image rights for the current protected subsystem.

Format

SYS$SUBSYSTEM enbflg

C Prototype

int sys$subsystem (unsigned int enbflg);

Argument

enbflg

OpenVMS usage: boolean

type: longword (unsigned)

access: read only

mechanism: by value

Value specifying whether the protected subsystem identifiers are to be saved or restored. If the enbflg argument is set to 0, the active subsystem is saved. If it is set to 1, the subsystem is restored.

Description

A protected subsystem image is a main image that has in its access control list a special type of ACE that names a set of identifiers and their attributes. Whenever the operating system activates a main image that has protected subsystem identifiers associated with it, these identifiers are automatically granted to the process for the duration of the image.
In essence, a protected subsystem provides the same behavior as if the image had been installed with the identifiers. Subsystem identifiers are sometimes referred to as image rights, in contrast to process rights and system rights.
The Subsystem service provides an easy way for a protected subsystem image to dynamically save and restore its subsystem identifiers. A protected subsystem might choose to turn off its subsystem identifiers at certain times to temporarily revoke the user's access to the objects comprising the protected subsystem. For example, DCL uses the $SUBSYSTEM service to temporarily remove any image identifiers from the process during Ctrl/Y interrupt processing.
The image rights are saved in the process control region and automatically deleted on image rundown ($RMSRUNDWN).
For more information about protected subsystems, refer to the OpenVMS Guide to System Security.
Required Access or Privileges

None
Required Quota

None
Related Services

None

Condition Values Returned

SS$_WASCLR The service completed successfully; protected subsystem had no identifiers associated with it.

SS$_WASSET The service completed successfully; protected subsystem had identifiers associated with it.

Contents

Index

privacy and legal statement

4527PRO_112.HTML

SS$_NORMAL	If returned in R0, the request was successfully queued. If 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 to the caller.
SS$_ALRCURTID	Either: An attempt was made to make the transaction specified by the tid argument the default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process had an unended default transaction. The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process was in progress.
SS$_BADPARAM	Either the options flags were invalid or the tid argument was omitted but the bid argument was not zero.
SS$_BRANCHSTARTED	There has already been a call to $START_BRANCH on the local node specifying that TID and BID (returned only if the node specified by the tm_name argument was the local node).
SS$_CONNECFAIL	The node specified by the tm_name argument was not the local node, and there was no communications link between the DECdtm transaction managers on the local node and the specified node.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_EXQUOTA	The job buffered I/O byte limit quota (BYTLM) 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$_INVBUFLEN	The string passed in the tx_class argument was longer than 31 characters, or the string passed in the tm_name argument was longer than 256 characters.
SS$_NOLOG	The local node did not have a transaction log.
SS$_NOSUCHBID	Either: The specified BID was not returned by any call to $ADD_BRANCH or $JOIN_RM on the local node (returned only if the node specified by the tm_name argument was the local node). An BID of zero was supplied.
SS$_NOSUCHTID	The local node did not have any branches in the specified transaction (returned only if the node specified by the tm_name argument was the local node).
SS$_TPDISABLED	The TP_SERVER process was not running on the local node.
SS$_WRONGSTATE	The transaction was in the wrong state for the attempted operation because either: An abort event has occurred for the transaction. A call to $END_TRANS to end the transaction is in progress and it is now too late to add a new branch to the transaction.

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

SS$_NORMAL	The service completed successfully.
SS$_AFR_NOT_ENABLED	The $START_ALIGN_FAULT_REPORT service has not been called.

SS$_NORMAL	The service completed successfully.
SS$_NOPRIV	The caller lacks sufficient privilege.
SS$_AFR_NOT_ENABLED	The $START_ALIGN_FAULT_REPORT service has not been called.

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

SS$_WASCLR	The service completed successfully; protected subsystem had no identifiers associated with it.
SS$_WASSET	The service completed successfully; protected subsystem had identifiers associated with it.