HP OpenVMS System Services Reference Manual

$SPACE

The Space service lets you space (skip) a tape file forward or backward a specified number of blocks.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.

$START_ALIGN_FAULT_REPORT (Alpha and I64)

On Alpha and I64 systems, initializes user image alignment fault reporting.

Format

SYS$START_ALIGN_FAULT_REPORT report_method ,report_buffer ,buffer_length

C Prototype

int sys$start_align_fault_report (int report_method, void *report_buffer, int buffer_length);

Arguments

report_method

OpenVMS usage: longword_signed

type: longword (signed)

access: read

mechanism: by value

Method by which image alignment faults are to be reported.
The following table shows valid values for the report_method argument:

Value Meaning

AFR$C_BUFFERED Alignment fault PCs and fault addresses are saved in a user-supplied buffer.

AFR$C_EXCEPTION Alignment faults are elevated to user mode exceptions.

report_buffer

OpenVMS usage: address

type: longword (unsigned)

access: read

mechanism: by reference

The 32-bit address of the buffer into which to write the fault data. The report_buffer argument is needed only if the value of the report_method argument is AFR$C_BUFFERED.
buffer_length

OpenVMS usage: byte count

type: longword (signed)

access: read

mechanism: by value

Length of the buffer specified in the report_buffer argument.
The buffer must have a minimum size of AFR$K_USER_LENGTH + 32. However, a larger buffer allows for more information to be collected.

Value	Meaning
AFR$C_BUFFERED	Alignment fault PCs and fault addresses are saved in a user-supplied buffer.
AFR$C_EXCEPTION	Alignment faults are elevated to user mode exceptions.

Description

The Start Alignment Fault Reporting service initializes user image alignment fault reporting.
The $START_ALIGN_FAULT_REPORT service allows the user to gather alignment fault data for one image. Reporting is enabled for the life of the image. When the image terminates, the alignment fault reporting is disabled.
User alignment fault data can be written to a buffer or broadcast as an informational exception message.
If the AFR$C_BUFFERED value is given in the report_method buffer, alignment fault PCs and fault addresses are saved in a user-supplied buffer.
The following diagram illustrates the format in which user alignment fault data is stored in the buffer:

If the AFR$C_EXCEPTION value is given in the report_method argument, alignment faults are elevated to user mode exceptions. These exceptions can be trapped in a handler; otherwise, an informational exception message might be broadcast and the program continues to execute.

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, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The buffer specified in the report_buffer argument is not accessible.

SS$_AFR_ENABLED The service has already been called for this image.

SS$_ARG_GTR_32_BITS The report buffer's virtual address lies in 64-bit virtual address space.

SS$_ALIGN The buffer specified in the report_buffer argument is not quadword aligned.

SS$_BADPARAM The buffer size is smaller than that defined by the AFR$K_USER_LENGTH + 32 symbol.

Example


#include <afrdef> #include <stdio> #include <ssdef> #define USER_BUFFER_ITEMS 10 #define GET_BUFFER_SIZE USER_BUFFER_ITEMSAFR$K_USER_LENGTH #define SAVE_BUFFER_SIZE 128+64 #define fault_pc afr$l_fault_pc_l #define fault_va afr$l_fault_va_l static int usr_buff_len; static char usr_buff; static int rep_method; void cause_af() { int addr; int ptr; int arr[2]; addr = (int) &arr[0]; ptr = (int ) ++addr; ptr = 1; / cause alignment fault / } main() { int i; char get_buffer[GET_BUFFER_SIZE]; struct afrdef data_item; int offset; int status; int return_size; rep_method = AFR$C_BUFFERED; usr_buff_len = SAVE_BUFFER_SIZE; usr_buff = (char )malloc (usr_buff_len); if(( status = sys$start_align_fault_report(rep_method, usr_buff, usr_buff_len)) != SS$_NORMAL) return(status); for (i=0;i<USER_BUFFER_ITEMS;i++) cause_af(); while (((status = sys$get_align_fault_data (get_buffer, GET_BUFFER_SIZE, &return_size)) > 0) && (return_size > 0)) { / got some data, print it / offset = 0; while (offset < return_size) { data_item = (struct afrdef )(&get_buffer[offset]); printf ("Alignment fault at PC = %8.8X, VA = %8.8X\n", data_item->fault_pc, data_item->fault_va); offset += AFR$K_USER_LENGTH; } } return (status); }

#include <afrdef>  
#include <stdio> 
#include <ssdef> 
 
#define USER_BUFFER_ITEMS  10 
#define GET_BUFFER_SIZE    USER_BUFFER_ITEMS*AFR$K_USER_LENGTH 
#define SAVE_BUFFER_SIZE   128+64 
 
#define fault_pc afr$l_fault_pc_l 
#define fault_va afr$l_fault_va_l 
 
static int usr_buff_len; 
static char *usr_buff; 
static int rep_method; 
 
 
void 
cause_af() 
{ 
  int     addr; 
  int     *ptr; 
  int    arr[2]; 
 
  addr = (int) &arr[0]; 
  ptr = (int *) ++addr; 
  *ptr = 1;    /* cause alignment fault */ 
} 
 
 
main() 
{ 
  int            i; 
  char           get_buffer[GET_BUFFER_SIZE]; 
  struct afrdef  *data_item; 
  int            offset; 
  int            status; 
  int            return_size; 
 
  rep_method = AFR$C_BUFFERED; 
  usr_buff_len = SAVE_BUFFER_SIZE; 
  usr_buff = (char *)malloc (usr_buff_len); 
  if(( status = sys$start_align_fault_report(rep_method, usr_buff, 
               usr_buff_len)) 
      != SS$_NORMAL) return(status); 
 
  for (i=0;i<USER_BUFFER_ITEMS;i++) 
    cause_af(); 
 
  while (((status = sys$get_align_fault_data (get_buffer, 
                GET_BUFFER_SIZE, 
                &return_size)) > 0) && 
         (return_size > 0)) { 
    /* got some data, print it */ 
    offset = 0; 
    while (offset < return_size) { 
      data_item = (struct afrdef *)(&get_buffer[offset]); 
      printf ("Alignment fault at PC = %8.8X, VA = %8.8X\n", 
        data_item->fault_pc, data_item->fault_va); 
      offset += AFR$K_USER_LENGTH; 
    } 
  } 
 
  return (status); 
}

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

$START_BRANCH

Adds a new branch to a transaction.

Format

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

C Prototype

int sys$start_branch (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],...);

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-57. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-57 $START_BRANCH Option Flags
Flag Name Description

DDTM$M_BRANCH_UNSYNCHED Specifies that the new branch is unsynchronized.
If this flag is clear, the new branch is synchronized.

DDTM$M_NONDEFAULT Set this flag if you do not want the transaction to be the default transaction of the calling process. If this flag is clear, the transaction becomes the default transaction of the calling process.
An error is returned if this flag is clear and the calling process has an current default transaction.

DDTM$M_SYNC Specifies successful synchronous completion 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

The 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_BRANCH Option Flags**
Flag Name	Description
DDTM$M_BRANCH_UNSYNCHED	Specifies that the new branch is unsynchronized. If this flag is clear, the new branch is synchronized.
DDTM$M_NONDEFAULT	Set this flag if you do not want the transaction to be the default transaction of the calling process. If this flag is clear, the transaction becomes the default transaction of the calling process. An error is returned if this flag is clear and the calling process has an current default transaction.
DDTM$M_SYNC	Specifies successful synchronous completion 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

The AST routine 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 same access mode as that of the caller of the $START_BRANCH service.

astprm

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

The AST parameter passed to the AST routine specified by the astadr argument.

tid

OpenVMS usage:	trans_id
type:	octaword (unsigned)
access:	read only
mechanism:	by reference

The identifier (TID) of the transaction to which the new branch will be added.

tm_name

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

The name of the node on which the call was made to $ADD_BRANCH that authorized the new branch to be added to the transaction. Note that this cannot be a cluster alias.

To ensure smooth operation in a mixed-network environment, refer to the chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for information on defining node names.

bid

OpenVMS usage:	branch_id
type:	octaword (unsigned)
access:	read only
mechanism:	by reference

The identifier (BID) of the new branch that is to be added to the transaction.

An BID value of zero is invalid.

timout

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

Reserved to HP.

acmode

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

The access mode of the new branch in this process. This is the least privileged mode that a caller must be in to remove this branch from the transaction by calling $END_BRANCH. Note that it can be removed from the transaction by calling $ABORT_TRANS from any access mode.

This argument only influences the access mode of the first branch in this process. Subsequent branches have the same access mode as the first. The access mode of the new branch is the least privileged of:

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

Note that if a branch already exists in this process, then neither the access mode of the caller nor the access mode specified by the acmode argument may be less privileged than that branch.

The default value of this argument is the access mode 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 transaction on the local node if the transaction does not already have a transaction class on the local node. This string is passed in the event reports delivered to Resource Manager identifiers (RMIs) and Resource Manager (RM) participants on the local node.

This argument is ignored if the transaction already has a transaction class on the local node.

This string must be no longer than 31 characters.

Description

The $START_BRANCH system service:

Adds a new branch running in the calling process to the specified transaction.
Adds the local DECdtm transaction manager to the specified transaction if the local DECdtm transaction manager is not already a participant in that transaction.
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 a transaction started event to each RMI in the calling process that meets both of the following conditions:

Requested Transaction Started events for the corresponding transaction type (default or non-default)
Has an access mode that is the same as or more privileged than that specified in this call to $START_BRANCH.

The new branch should have been previously authorized. Authorization is provided either by a matching call to $JOIN_RM with the DDTM$M_COORDINATOR flag set or by a matching call to $ADD_BRANCH. Two calls, one to $ADD_BRANCH and one to $START_BRANCH or one to $JOIN_RM and one to $START_BRANCH, are said to be matching when the following conditions are true:

The same TID values are passed to both calls.
The BID returned by the call to $ADD_BRANCH or $JOIN_RM is the same as that passed to the call to $START_BRANCH.
The call to $START_BRANCH is made on the node identified by the tm_name argument passed to the call to $ADD_BRANCH or on the node on which the call to $JOIN_RM was made.
The call to $ADD_BRANCH or $JOIN_RM is made on the node identified by the tm_name argument passed to the call to $START_BRANCH.

$START_BRANCH does not check that there has been a matching call to $ADD_BRANCH or $JOIN_RM unless the tm_name argument passed to $START_BRANCH specifies the local node.

Note
The atomicity of the transaction is not guaranteed if there is a call to $START_BRANCH that does not have a matching call to $ADD_BRANCH or $JOIN_RM.

Preconditions for the successful completion of $START_BRANCH are:

The local node must have a DECdtm transaction log.
The TP_SERVER process must be running on the local node.
There must not have been a successful call to $START_BRANCH on the local node that passed the specified BID.
If the tm_name argument specifies the local node, there must have been a matching call to $ADD_BRANCH or $JOIN_RM on the local node.
If the DDTM$M_NONDEFAULT flag is clear, the calling process must not have an unended default transaction.
If this process already contains a branch of this transaction, then the access mode of the caller must be the same as or more privileged than the access mode of that branch.

$START_BRANCH may fail because:

Preconditions were not met.
An abort event occurred for the transaction.
A call to $END_TRANS to end the transaction is in progress and it is too late to add a new branch to the transaction.
The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process is in progress.

When $START_BRANCH completes successfully:

A new branch running in the calling process has been added to the transaction.
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, explicitly 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; see 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.

Contents

Index

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read
mechanism:	by value

OpenVMS usage:	address
type:	longword (unsigned)
access:	read
mechanism:	by reference

OpenVMS usage:	byte count
type:	longword (signed)
access:	read
mechanism:	by value

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The buffer specified in the report_buffer argument is not accessible.
SS$_AFR_ENABLED	The service has already been called for this image.
SS$_ARG_GTR_32_BITS	The report buffer's virtual address lies in 64-bit virtual address space.
SS$_ALIGN	The buffer specified in the report_buffer argument is not quadword aligned.
SS$_BADPARAM	The buffer size is smaller than that defined by the AFR$K_USER_LENGTH + 32 symbol.

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