Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

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

## $START_ALIGN_FAULT_REPORT (Alpha Only)

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

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

> The flags currently defined are shown in the following table:

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_099.HTML