HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index

Message Buffer Format for OPC$_RQ_CANCEL


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_CANCEL.
OPC$Z_MS_TARGET_CLASSES This 3-byte field contains a 24-bit bit vector that specifies which operator terminal types are to receive the cancellation request. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$L_MS_RQSTID This longword field contains a user-supplied longword message code.

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


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_TERME.
OPC$Z_MS_ENAB_TERMINALS This 3-byte field contains a user-supplied value. The value 0 indicates that the specified terminal is to be disabled for the specified operator classes. Any nonzero value indicates that the specified terminal is to be enabled for the specified operator classes.
OPC$B_MS_MASK This 4-byte field contains a 4-byte bit vector that specifies which operator terminal types are to be enabled or disabled for the specified terminal. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$W_MS_OUNIT This 2-byte field contains the unit number of the operator terminal to be enabled or disabled for the specified operator terminal types. 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 operator terminal to be enabled or disabled for the specified operator terminal types. The maximum total length of the string is 16 bytes. See the preceding field description (OPC$W_MS_OUNIT) to learn how to obtain the device name.

Message Buffer Format for OPC$_RQ_STATUS


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_STATUS.
Reserved This 3-byte field is reserved for future use.
Reserved This 4-byte field is reserved for future use.
OPC$W_MS_OUNIT This 2-byte field contains the unit number of the operator terminal whose status is to be requested. 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 operator terminal whose status is requested. 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.

Message Buffer Format for OPC$_RQ_LOGI


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_LOGI.
OPC$Z_MS_TARGET_CLASSES This 3-byte field contains a 24-bit bit vector that specifies which operator terminal types are to receive the cancellation request. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$L_MS_RQSTID This longword field contains a user-supplied value.

The value 0 specifies that the current operator log file is to be closed and a new log file opened with all classes enabled (OPC$B_MS_TARGET is ignored).

The value 1 specifies that the current operator log file is to be closed but no new log file is to be opened.

The value 2 specifies that the classes in OPC$B_MS_TARGET are added to the current operator log file classes. A log file is opened if necessary.

The value 3 specifies that the operator classes in OPCB_MS_TARGET are to be removed from the operator log file classes. If all classes are removed, the log file is closed.

OPC$W_MS_OUNIT This 2-byte field contains the unit number of the operator terminal that is making the initialization request. 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 operator terminal that is making the initialization request. 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.

chan


OpenVMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value

Channel assigned to the mailbox to which the reply is to be sent. The chan argument is a longword value containing the number of the channel. If you do not specify chan or specify it as the value 0 (the default), no reply is sent.

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

  • 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

#1

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

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


Previous Next Contents Index