Document revision date: 19 July 1999

Message Buffer Format for OPC$_RQ_REPLY

OPC$B_MS_TYPE	This 1-byte field contains the request code OPC$_RQ_REPLY.
Reserved	This 1-byte field is reserved for future use.
OPC$W_MS_STATUS	This 2-byte field contains the low-order word of the longword condition value that $SNDOPR returns in the mailbox specified by the chan argument. You can find a list of these longword condition values under Condition Values Returned in the Mailbox. To test the completion status, you need to extract the low-order word from the longword condition value and compare it to the contents of the OPC$W_MS_STATUS field.
OPC$L_MS_RPLYID	This 4-byte field contains a user-supplied message code.
OPC$W_MS_OUNIT	This 2-byte field contains the unit number of the terminal to which the operator reply is to be sent. To obtain the unit number of the terminal, you can call $GETDVI, specifying the DVI$_FULLDEVNAM item code. The information returned will consist of the node name and device name as a padded string. Because the unit number is found on the tail end of the string, you must parse the string. One way to do this is, starting from the tail end, to search for the first alphabetic character; the digits to the right of this alphabetic character constitute the unit number. After extracting the unit number, count the remaining characters in the string. Then, construct a counted ASCII string and use this for the following field, OPC$T_MS_ONAME.
OPC$T_MS_ONAME	This variable-length field contains a counted ASCII string specifying the device name of the terminal that is to receive the operator reply. The maximum total length of the string is 14 bytes. See the preceding field description (OPC$W_MS_OUNIT) to learn how to obtain the device name.
OPC$L_MS_OTEXT	This variable-length field contains an ASCII string specifying operator-written text to be sent to the user terminal. The length of the string must be in the range 0 to 255 bytes. This field is optional.

Message Buffer Format for OPC$_RQ_TERME

Message Buffer Format for OPC$_RQ_STATUS

Message Buffer Format for OPC$_RQ_LOGI

chan

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

Description

The $SNDOPR service performs the following functions:

• Sends a user request to operator terminals
• Sends a user cancellation request to operator terminals
• Sends an operator reply to a user terminal
• Enables an operator terminal
• Displays the status of an operator terminal
• Initializes the operator log file

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-1998 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-1998 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-1998 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:

• Enabling a terminal as an operator's terminal
• Replying to or canceling a user's request
• Initializing the operator communication log file

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

#include <ssdef.h> 
#include <opcdef.h> 
#include <string.h> 
#include <descrip.h> 
#include <starlet.h> 
#include <lib$routines.h> 
 
char    input_buffer[256];      /* Input buffer, if needed */ 
 
/* VMS descriptors: */ 
$DESCRIPTOR(input_desc, input_buffer); 
$DESCRIPTOR(prompt_desc, "Request> "); 
struct dsc$descriptor req_desc; 
 
main(int argc, char *argv[]) 
{ 
    int status,                 /* Status of system calls */ 
        length = 0;             /* Length of message text */ 
    struct OPC request;         /* Request message buffer */ 
 
    /* Check for too many arguments on command line */ 
    if (argc > 2) 
        return (SS$_OVRMAXARG); 
 
    /* See if request string present on command line... */ 
    if (argc > 1) 
    { 
        /* It is.  Compute length and copy pointer */ 
        length = strlen(argv[1]); 
        input_desc.dsc$a_pointer = argv[1]; 
    } 
 
    /* If no message present, prompt user for message text */ 
    while (length == 0) 
    { 
        status = lib$get_input(&input_desc, &prompt_desc, &length); 
        if (status != SS$_NORMAL) 
            return (status); 
    }; 
 
    if (length > 128)           /* Limit message length */ 
        length = 128;           /*    to 128 characters */ 
 
    /* Set up request buffer... */ 
    request.opc$b_ms_type = OPC$_RQ_RQST; 
    request.opc$b_ms_target = OPC$M_NM_CENTRL; 
    request.opc$l_ms_rqstid = 0; 
    memcpy(&request.opc$l_ms_text, input_desc.dsc$a_pointer, length); 
 
    /* Set up request buffer descriptor and send message */ 
    req_desc.dsc$w_length = length + 8; 
    req_desc.dsc$a_pointer = (char *) &request; 
    return (sys$sndopr(&req_desc, 0)); 
} 
 
 
 
      

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

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 DEC Fortran for OpenVMS program enables the current terminal to receive OPER1 operator messages.

On Alpha 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); 
} 
 
 
      

---

Previous

Next

Contents

Index

	privacy and legal statement
4527PRO_092.HTML