OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

This example shows how to use the $START_ALIGN_FAULT_REPORT service to initialize user image alignment fault reporting on Alpha systems.

$START_TRANS

Starts a new transaction.

Format

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

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 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. The flags currently defined are shown in the following table. All undefined bits must be 0. If this argument is omitted, no flags are set.

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.
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_PROCESS Set this flag if you do not want the DECdtm transaction manager to try to abort the transaction if the current image terminates.
If this flag is clear, when the current image terminates (normally or abnormally), the DECdtm transaction manager will abort the transaction if it has not already committed.
An error is returned if this flag is set and the caller is in user mode.

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.

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. 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_PROCESS	Set this flag if you do not want the DECdtm transaction manager to try to abort the transaction if the current image terminates. If this flag is clear, when the current image terminates (normally or abnormally), the DECdtm transaction manager will abort the transaction if it has not already committed. An error is returned if this flag is set and the caller is in user mode.
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 value
access:	call without stack unwinding
mechanism:	by reference

AST routine that is executed when the service completes. The astadr argument is the address of this routine. This 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:	write only
mechanism:	by reference

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

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.

The time value is a binary number, in units of 100 nanoseconds.

A positive time value specifies an offset from the system base time. The system base time is 00:00 hours November 17, 1858.

A negative time value specifies an offset from the current time to some time in the future.

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

The least privileged access mode that the calling process must be in to end the transaction by calling $END_TRANS. Note that the calling process can end the transaction by calling $ABORT_TRANS from any access mode.

The access mode that the calling process must be in to end the transaction by calling $END_TRANS is whichever 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, it defaults to the access mode of the caller.

Description

The Start Transaction service starts a new transaction that is to be coordinated by the DECdtm distributed transaction manager.
$START_TRANS creates a unique transaction identifier for the new transaction. The same identifier can never be created by any other call to $START_TRANS on any node.
Each process can have a default transaction. This is the transaction that is assumed when the process:

Invokes resource manager operations without specifying a transaction identifier, for resource managers such as RMS Journaling that support default transactions
Calls $END_TRANS or $ABORT_TRANS without specifying a tid argument

By default, the new transaction becomes the default transaction of the calling process. If you want to start a new transaction and the calling process already has a default transaction, set the DDTM$M_NONDEFAULT flag.
Required Access or Privileges

None
Required Quotas

ASTLM, BYTLM
Related Services

$ABORT_TRANS, $ABORT_TRANSW, $END_TRANS, $END_TRANSW, $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$_ALCURTID An attempt was made to start a default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process already had a default transaction.

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 Not enough arguments were supplied.

SS$_INSFMEM There was insufficient system dynamic memory for the operation.

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

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

SS$_WRONGACMODE The DDTM$M_PROCESS flag was set and the caller was in user mode.

$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, see 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.

$SUSPND

Allows a process to suspend itself or another process.

Format

SYS$SUSPND [pidadr] ,[prcnam] ,[flags]

C Prototype

int sys$suspnd (unsigned int *pidadr, void *prcnam, unsigned int flags);

Arguments

pidadr

OpenVMS usage: process_id

type: longword (unsigned)

access: modify

mechanism: by reference

Process identification (PID) of the process to be suspended. The pidadr argument is the address of the longword PID. The pidadr argument can refer to a process running on the local node or a process running on another node in the OpenVMS Cluster system.
You must specify the pidadr argument to suspend a process whose UIC group number is different from that of the calling process.
prcnam

OpenVMS usage: process_name

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Name of the process to be suspended. The prcnam argument is the address of a character string descriptor pointing to the process name. A process running on the local node can be identified with a 1- to 15-character string. To identify a process on a particular node on a cluster, specify the full process name, which includes the node name as well as the process name. The full process name can contain up to 23 characters.
A process name is implicitly qualified by its UIC group number. Because of this, you can use the prcnam argument only to suspend processes in the same UIC group as the calling process.
To suspend processes in other groups, you must specify the pidadr argument.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Longword of bit flags specifying options for the suspend operation. Currently, only bit 0 is used for the flags argument. When bit 0 is set, the process is suspended at kernel mode and ASTs are not deliverable to the process.
To request a kernel mode suspend, the caller must be in either kernel mode or executive mode. The default (bit 0 is clear) is to suspend the process at supervisor mode, where executive or kernel mode ASTs can be delivered to the process. If executive or kernel mode ASTs have been delivered to a process suspended at supervisor mode, that process will return to its suspended state after the AST routine executes.

Description

The Suspend Process service allows a process to suspend itself or another process.
A suspended process can receive executive or kernel mode ASTs, unless it is suspended at kernel mode. If a process is suspended at kernel mode, the process cannot receive any ASTs or otherwise be executed until another process resumes or deletes it. If you specify neither the pidadr nor the prcnam argument, the caller process is suspended.
If the longword value at address pidadr is 0, the PID of the target process is returned.
The $SUSPND service requires system dynamic memory.
The $SUSPND service completes successfully if the target process is already suspended.
Unless it has pages locked in the balance set, a suspended process can be removed from the balance set to allow other processes to execute.
Note that a kernel mode suspend request can override a supervisor mode suspend state, but a supervisor suspend request cannot override a kernel mode suspend state.
The Resume Process ($RESUME) service allows a suspended process to continue. If one or more resume requests are issued for a process that is not suspended, a subsequent suspend request completes immediately; that is, the process is not suspended. No count is maintained of outstanding resume requests.
Required Access or Privileges

Depending on the operation, the calling process might need one of the following privileges to use $SUSPND:

GROUP privilege to suspend another process in the same group, unless the process to be suspended has the same UIC as the calling process
WORLD privilege to suspend any other process in the system

Required Quota

None
Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $WAKE

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The process name string or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller.

SS$_INCOMPAT The remote node is running an incompatible version of the operating system.

SS$_INSFMEM The system dynamic memory is insufficient for completing the service.

SS$_IVLOGNAM The specified process name has a length of 0 or has more than 15 characters.

SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified.

SS$_NOPRIV The target process was not created by the caller and the calling process does not have GROUP or WORLD privilege, or flag bit 0 was set from outer mode.

SS$_NOSUCHNODE The process name refers to a node that is not currently recognized as part of the OpenVMS Cluster system.

SS$_NOSUSPEND The process was previously marked as not suspendable by the PCB$V_NOSUSPEND flag.

SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)

SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)

SS$_WAIT_CALLERS_MODE Bit 1 was used in the flags argument.

Contents

Index

Legal

 
4527PRO_093.HTML

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	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$_ALCURTID	An attempt was made to start a default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process already had a default transaction.
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	Not enough arguments were supplied.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_NOLOG	The local node did not have a transaction log.
SS$_TPDISABLED	The TP_SERVER process was not running on the local node.
SS$_WRONGACMODE	The DDTM$M_PROCESS flag was set and the caller was in user mode.

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.

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by reference

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