HP OpenVMS System Services Reference Manual
Previous Contents Index

If a reply from the operator is desired, you must specify the chan argument.

Description

The $SNDOPR service performs the following functions:

This system service requires system dynamic memory; it cannot be called from kernel mode.

The general procedure for using this service is as follows:

  1. Construct the message buffer and place its final length in the first word of the buffer descriptor.
  2. Call the $SNDOPR service.
  3. Check the condition value returned in R0 to make sure the request was successfully made.
  4. Issue a read request to the mailbox specified, if any.
  5. When the read operation completes, check the 2-byte condition value in the OPC$W_MS_STATUS field to make sure that the operation was performed successfully.

The format of messages displayed on operator terminals follows: 


%%%%%%%%%%%  OPCOM   dd-mmm-yyyy hh:mm:ss.cc 
message specific information

The following example shows the message displayed on a terminal as a result of a request to enable that terminal as an operator terminal: 


%%%%%%%%%%%  OPCOM   30-DEC-2001 13:44:40.37 
Operator _NODE$LTA5: has been enabled, username HOEBLE

The following example shows the message displayed on an operator terminal as a result of a request to display the status of that operator terminal: 


%%%%%%%%%%%  OPCOM   30-DEC-2001 12:11:10.48 
Operator status for operator _NODE$OPA0: 
CENTRAL, PRINTER, TAPES, DISKS, DEVICES, CARDS, CLUSTER, SECURITY, 
OPER1, OPER2, OPER3, OPER4, OPER5, OPER6, OPER7, OPER8, OPER9, 
OPER10, OPER11, OPER12

The following example shows the message displayed on an operator terminal as a result of a user request: 


%%%%%%%%%%%  OPCOM   30-DEC-2001 12:57:32.25 
Request 1285, from user ROSS on NODE_NAME 
Please mount device _NODE$DMA0:

Required Access or Privileges

OPER privilege is required for the following functions:

In addition, the operator must have SECURITY privilege to affect security functions.

Required Quota

None

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW

Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The message buffer or buffer descriptor cannot be read by the caller.
SS$_BADPARAM The specified message has a length of 0 or has more than 986 bytes.
SS$_DEVNOTMBX The channel specified is not assigned to a mailbox.
SS$_INSFMEM The service was called from kernel mode or the system dynamic memory is insufficient for completing the service.
SS$_IVCHAN You specified an invalid channel number. An invalid channel number is one that is 0 or a number larger than the number of channels available.
SS$_MBFULL The mailbox used to support communication is full. Retry at a later time.
OPC$_NOPERATOR The service completed successfully; the Operator Communications Manager (OPCOM) is not running and the message will not be sent. Note that OPC$_NOPERATOR is a success status and must be tested for explicitly.
SS$_NOPRIV The process does not have the privilege to reply to or cancel a user's request; the process does not have read/write access to the specified mailbox; or the channel was assigned from a more privileged access mode.

Condition Values Returned in the Mailbox

OPC$_BLANKTAPE The service completed successfully; the operator responded with the DCL command REPLY/BLANK_TAPE=n.
OPC$_INITAPE The service completed successfully; the operator responded with the DCL command REPLY/INITIALIZE_TAPE=n.
OPC$_NOPERATOR The service completed successfully; no operator terminal was enabled to receive the message.
OPC$_RQSTCMPLTE The service completed successfully; the operator completed the request.
OPC$_RQSTPEND The service completed successfully; the operator will perform the request when possible.
OPC$_RQSTABORT The operator could not satisfy the request.
OPC$_RQSTCAN The caller canceled the request.

Examples

#1 

#include <descrip.h>  /* VMS string descriptors */ 
#include <lib$routines.h>           /* VMS LIB$ routine prototypes */ 
#include <opcdef.h>      /* $SNDOPR request structures and definitions */ 
#include <ssdef.h>      /* VMS SS$_x status values */ 
#include <stsdef.h>      /* $VMS_STATUS_SUCCESS */  
#include <starlet.h>      /* VMS system service prototypes */ 
#include <stddef.h>      /* Define offsetof */ 
#include <stdlib.h>      /* malloc, free, et. al. */     
#include <string.h>      /* string functions, memcpy, et. al. */ 
 
 
main(int argc, char *argv[]) 
{ 
    int status;                         /* Status of system calls */ 
    short length = 0;                   /* Length of message text */ 
 
    union                               /* Target OPC$_ classes bitmask */ 
    { 
        int longword_value;             /*   Longword, for use with OPC$M_ values */ 
        char byte_value[3];             /*   By byte, to load opc$z_ms_target_classes */ 
    }   target_classes; 
 
    struct _opcdef *sndopr_rqst;        /* Pointer to $SNDOPR message buffer */ 
 
    /* 
     * Descriptors for input message text string, $SNDOPR message buffer, and prompt. 
     */ 
    struct dsc$descriptor input_desc = { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, 0 }; 
    struct dsc$descriptor req_desc   = { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, 0 }; 
    $DESCRIPTOR(prompt_desc, "Request> "); 
 
 
    /* 
     * Check for too many arguments on command line 
     */ 
    if (argc > 2) 
        return SS$_OVRMAXARG; 
 
    /* 
     * If provided on the command line, use that as the message string. 
     */ 
    if (argc > 1) 
    { 
        length = strlen(argv[1]); 
        input_desc.dsc$a_pointer = argv[1]; 
    } 
 
    /* 
     * If no message text so far, prompt the user for the message text. 
     * Use a dynamic string descriptor to contain the supplied text. 
     */ 
    while (length == 0) 
    { 
        input_desc.dsc$b_class = DSC$K_CLASS_D; 
        status = lib$get_input(&input_desc, &prompt_desc, &length); 
        if ( !$VMS_STATUS_SUCCESS(status) ) 
            return status; 
    }; 
 
    /* 
     * Allocate a $SNDOPR message structure with enough room for the 
     * message text and the fixed header for a OPC$_RQ_RQST message. 
     */ 
    sndopr_rqst = malloc( length + offsetof(struct _opcdef,opc$l_ms_text) ); 
    if (sndopr_rqst == 0) 
        return SS$_INSFMEM; 
 
    /* 
     * Fill in the $SNDOPR message structure, including the text. 
     */ 
    sndopr_rqst->opc$b_ms_type = OPC$_RQ_RQST; 
    sndopr_rqst->opc$l_ms_rqstid = 0; 
 
    target_classes.longword_value = OPC$M_NM_CENTRL; 
 
    sndopr_rqst->opc$z_ms_target_classes[0] = target_classes.byte_value[0]; 
    sndopr_rqst->opc$z_ms_target_classes[1] = target_classes.byte_value[1]; 
    sndopr_rqst->opc$z_ms_target_classes[2] = target_classes.byte_value[2]; 
 
    memcpy(&sndopr_rqst->opc$l_ms_text, input_desc.dsc$a_pointer, length); 
 
    /* 
     * Set up the descriptor for the $SNDOPR message structure and call 
     * the $SNDOPR service. 
     */ 
    req_desc.dsc$w_length = length + offsetof(struct _opcdef,opc$l_ms_text); 
    req_desc.dsc$a_pointer = (char *) sndopr_rqst; 
 
    status = sys$sndopr(&req_desc, 0); 
 
    /* 
     * Clean up time. Free the $sndopr request block. If we got a dynamic 
     * string for the input message text, free that too. 
     */ 
    free( sndopr_rqst); 
 
    if ( input_desc.dsc$b_class == DSC$K_CLASS_D ) 
        lib$sfree1_dd( (unsigned __int64 *) &input_desc ); 
 
    return status; 
}

This example allows you to build an operator request and send the request to the operator.

#2 

IMPLICIT NONE 
 
        ! Symbol definitions 
        INCLUDE '($DVIDEF)' 
        INCLUDE '($OPCDEF)' 
 
        ! Structures for SNDOPR 
        STRUCTURE /MESSAGE/ 
         UNION 
          MAP 
           BYTE TYPE, 
        2       ENABLE(3) 
           INTEGER*4 MASK 
           INTEGER*2 OUNIT 
           CHARACTER*14 ONAME 
          END MAP 
          MAP 
           CHARACTER*24 STRING 
          END MAP 
         END UNION 
        END STRUCTURE 
        RECORD /MESSAGE/ MSGBUF 
        ! Length of MSGBUF.ONAME 
        INTEGER*4 ONAME_LEN 
 
        ! Status and routines 
        INTEGER*4 STATUS, 
        2         LIB$GETDVI, 
        2         SYS$SNDOPR 
 
        ! Type 
        MSGBUF.TYPE = OPC$_RQ_TERME 
        ! Enable 
        MSGBUF.ENABLE(1) = 1 
        ! Operator type 
        MSGBUF.MASK = OPC$M_NM_OPER1 
        ! Terminal unit number 
        STATUS = LIB$GETDVI (DVI$_UNIT, 
        2                    , 
        2                    'SYS$OUTPUT', 
        2                    MSGBUF.OUNIT,,) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
        ! Terminal name 
        STATUS = LIB$GETDVI (DVI$_FULLDEVNAM, 
        2                    , 
        2                    'SYS$OUTPUT',, 
        2                    MSGBUF.ONAME, 
        2                    ONAME_LEN) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
        ! Remove unit number from ONAME and set up counted string 
        ONAME_LEN = ONAME_LEN - 3 
        MSGBUF.ONAME(2:ONAME_LEN+1) = MSGBUF.ONAME(1:ONAME_LEN) 
        MSGBUF.ONAME(1:1) = CHAR(ONAME_LEN) 
        ! Call $SNDOPR 
        STATUS = SYS$SNDOPR (MSGBUF.STRING,) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
        END

This HP Fortran for OpenVMS program enables the current terminal to receive OPER1 operator messages.

$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 Integrity servers)

On Alpha and Integrity server 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.

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

Table SYS-56 $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:

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:

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:

Previous Next Contents Index