We've briefly described OPCOM before. In this article, we will look at the implementation (and document the features) necessary to support REPLY. There are additional features that we will discuss in future articles. The provided documentation only includes what the code currently covers.

There are some differences from VMS. On VMS, OPCOM is started with the SYS$SYSTEM:STARTUP script. One of the things this script does is start OPCOM detached. In fact, as far as I can tell, the only way to run something detached on VMS is to start it detached - or to hang up on a remote connection. Though I an hesitant to add a whole new feature not in the documentation, I cannot think of any potential security (or other) concern. I can see other uses for a way to detach an existing process, which we will use in the future. So in OPCOM, we will use the DETACH service to detach ourselves. First the admin documentation.

OPCOM
The operator communication manager (OPCOM) is a system service used to allow users and operators to communicate and logs events in files. Messages come to OPCOM from system events, programs, and users and then are logged and/or sent to operators for action.

OPCOM runs as a detached process. Terminals can be specifically designated as operator terminals. By default TERMA0: is designated as an operator terminal. Messages can be sent from OPCOM to operator terminals. Programs such as REPLY can be used to control OPCOM. OPCOM also writes messages to the operator log file, which has the default name of sys$manager:operator.log.

Operator messages have message classes that can be used to filter them. The classes are:

Name	Description
GENERAL	General messages not covered by any other message class.
MAIL	Messages sent by the MAIL utility.
OPCOM	Urgent messages sent by OPCOM.
PHONE	Messages sent by the PHONE utility.
QUEUE	Messages sent by Queue manager.
SHUTDOWN	Shutdown messages.
UCL	Messages sent for Control-T status.
URGENT	Urgent messages.
USER1-USER16	User-defined messages sent by some programs.

Operator terminals can be enabled/disabled for certain message classes. Also, OPCOM can be enabled/disabled for certain message classes. The OPC$OPA0_CLASSES symbol can be defined to indicate which message classes are sent to TERMA0: when OPCOM starts. If the symbol is not defined, is null, or has an invalid class name in it, all message classes are enabled for the terminal. Otherwise it is a comma-delimited list of class names.

OPCOM is started automatically on system startup, by default. To manually start it, use the command:

$ SYS$SYSTEM:OPCOM

To control OPCOM, use the REPLY utility. See the documentation on that utility for details. Some system symbols can be used to control the operation of OPCOM.

Name	Description
OPC$LOGFILE_CLASSES	Message classes to log to the operator log file.
OPC$LOGFILE_NAME	Name of the operator log file.
OPC$OPA0_CLASSES	Message classes to automatically assign to TERMA0:
OPCOM$MAILBOX	Mailbox associated with OPCOM messages.

Messages sent to OPCOM through the mailbox have two forms: commands and messages. Commands are denoted by a message beginning with an ESCape character, a class index, another ESCape, and then the message text. If the message doesn't start with an ESCape it is a command. However, unrecognized commands are treated as general messages.

The message format is:

^Eclass^Emessage

where "class" is the message class, "message" is the message text, and the superscript E indicates the ASCII ESCape character. Example:

^E5^ESystem is shutting down

Commands are:

Command	Description
enabled	Enable messages for a terminal. Format: enabled=<term:>{<class>{,...} where <term> is the terminal to affect and <class> is the message class to enable. This can be a comma-delimited list. If no list or class is provided, all classes are enabled. Example: enabled=terma9:queue,phone
disabled	Disable messages for a terminal. Format: enabled=<term:>{<class>{,...} where <term> is the terminal to affect and <class> is the message class to disable. This can be a comma-delimited list. If no list or class is provided, all classes are disabled. Example: disabled=terma9:
log	Open operator log file.
unlog	Close operator log file.

function Run : int64 ;

var E, Extended_Error : int64 ;
    OS : POS_UOS ;
    T : string ;

begin
    OS := new( POS_UOS, Init ) ;
    E := _OPCOM( Extended_Error, T ) ;
    if( E <> 0 ) then
    begin
        if( Extended_Error <> 0 ) then
        begin
            OS^.OutputLn( 0, LIB_Get_Exception_Text( 0, Extended_Error ) ) ;
            OS^.OutputLn( 0, '    \' + T + '\' ) ;
        end ;
        OS^.OutputLn( 0, LIB_Get_Exception_Text( 0, E ) ) ;
    end ;
    OS.Free ;
    SYS_EXIT( 0 ) ;
end ;

type TClasses = array[ 0..22 ] of boolean ;

     TTerm = class
                 public
                     Name : string ;
                     Classes : TClasses ;
             end ;

function _OPCOM( var Extended_Error : int64 ; Extended_Text : string ) : int64 ;

var Buffer : PAnsiChar ;
    Classes, Disabled : TClasses ;
    Context : int64 ;
    Descriptors : array[ 0..1 ] of PPSCAN_Reference_Descriptor ;
    E : int64 ;
    IOSB : TIOSB ;
    OS : POS_UOS ;
    F, Security_File : TCOM_UOS_File ; // Log and security files
    I : integer ;
    Info : TMessage_Info ;
    Logfile_Name : string ;
    Message_Class : integer ;
    Msg, SRB : TSRB ;
    S, SL : string ;
    Term : TTerm ;
    Terms : TList ; // List of operator terminals (TTerm instances)

begin
    // Setup...
    Result := 0 ;
    Extended_Error := 0 ;
    fillchar( Classes, sizeof( Classes ), -1 ) ; // Enable all classes
    Terms := TList.Create ;

    // Enable terma0, all classes, by default
    Term := TTerm.Create ;
    Terms.Add( Term ) ;
    Term.Name := 'terma0:' ;
    fillchar( Term.Classes, sizeof( Term.Classes ), -1 ) ;
    S := Get_Symbol( 'OPC$OPA0_CLASSES' ) ;
    if( S <> '' ) then
    begin
        fillchar( Classes, sizeof( Classes ), 0 ) ; // Disable all classes
        Parse_Classes( S, Term.Classes ) ;
    end ;

    // Ensure that OPCOM isn't already running...
    S := Normalize_Filename( 'sys$system:opcom.exe' ) ;
    Context := 0 ;
    fillchar( Descriptors, sizeof( Descriptors ), 0 ) ;
    Descriptors[ 0 ].MBO := $FFFF ;
    Descriptors[ 0 ].MBMO := $FFFFFFFF ;
    Descriptors[ 0 ].Code := PSCAN_FULL_IMAGE ;
    Descriptors[ 0 ].Length := length( S ) ;
    Descriptors[ 0 ].Address := int64( PChar( S ) ) ;
    Descriptors[ 0 ].Flags := PSCAN_M_EQL ;
    SYS_Process_Scan( int64( @Context ), int64( @Descriptors ) ) ;
    SYS_GETJPIW( 0, int64( @Context ), 0, 0, 0, 0, 0 ) ;
    if( LIB_Get_Exception( 0 ) = 0 ) then // No exception - an OPCOM process already running
    begin
        Result := OPCOM_ALREADY ;
        exit ;
    end ;

Are there other ways we could check to see if the OPCOM service is already running? Actually not; at least not any that are foolproof. For instance, one might be tempted to use the OPCOM mailbox device as a means of determining this. But the mailbox is permanent, which means OPCOM could be stopped (by an abend or a killed process, for instance), but the mailbox would remain. So its existence only tells us that OPCOM once ran during this timesharing session - not whether or not it is currently running.

    // Determine messages classes defined in existing log file...
    Logfile_Name := 'SYS$MANAGER:OPERATOR.LOG' ;
    S := Get_Symbol( 'OPC$LOGFILE_NAME' ) ;
    if( S <> '' ) then
    begin
        Logfile_Name := S ;
    end ;
    F := Open_Binary_File( Logfile_Name, FAB_V_GET ) ;
    if( F = nil ) then
    begin
        if( Open_Error <> UOSErr_File_Not_Found ) then
        begin
            Extended_Error := UTIL_OPENERR ;
            Extended_Text := Logfile_Name ;
            Result := Open_Error ;
            exit ;
        end ;
        
        // Determine classes to log to log file...
        S := Get_Symbol( 'OPC$LOGFILE_CLASSES' ) ;
        if( S <> '' ) then
        begin
            fillchar( Classes, sizeof( Classes ), 0 ) ; // Disable all classes
            Parse_Classes( S, Classes ) ;
        end ;
    end else

    begin
        fillchar( Classes, sizeof( Classes ), 0 ) ; // Disable all classes
        while( not F.EOF ) do
        begin
            F.Readln( Buffer ) ;
            S := Ansistring( Buffer ) ;
            if( copy( S, 1, 7 ) = 'enable ' ) then
            begin
                S := copy( S, 8, length( S ) ) ;
                I := Class_Index( S ) ;
                if( I <> -1 ) then
                begin
                    Classes[ I ] := True ;
                end
            end else
            if( copy( S, 1, 8 ) = 'disable ' ) then
            begin
                S := copy( S, 9, length( S ) ) ;
                I := Class_Index( S ) ;
                if( I <> -1 ) then
                begin
                    Classes[ I ] := False ;
                end
            end ;
        end ;
        F.Close ;
        F := nil ;
    end ;

    // Create/open files...
    F := Open_Binary_File( Logfile_Name, FAB_V_GET or FAB_V_PUT or FAB_V_CIF or FAB_V_SUP ) ;
    if( F = nil ) then
    begin
        Extended_Error := UTIL_OPENERR ;
        Extended_Text := Logfile_Name ;
        Result := Open_Error ;
        exit ;
    end ;
    for I := low( Classes ) to high( Classes ) do // Write enabled classes to log file
    begin
        if( Classes[ I ] ) then
        begin
            F.Writeln( PChar( 'enable ' + Class_Name( I ) ) ) ;
        end ;
    end ;

The first thing we do in the loop is query the mailbox for the next message. If there are no messages, QIOW will wait until one is posted. We use the IO_READVBLK function.

        if( LIB_Get_Exception( 0 ) = 0 ) then
        begin
            setlength( S, IOSB.r_io_64.r_bcnt_32.l_bcnt ) ;
            move( Buffer[ 0 ], PChar( S )[ 0 ], length( S ) ) ;
            if( ( Info.Privileges and OPER ) = 0 ) then // No OPER privilege
            begin
                continue ;
            end ;

            // Process message...
            Message_Class := BRK_C_GENERAL ;
            if( copy( S, 1, 1 ) = ESC ) then
            begin
                S := copy( S, 2, length( S ) ) ;
                I := pos( ESC, S ) ;
                SL := copy( S, 1, I - 1 ) ;
                S := ' ' + copy( S, I + 1, length( S ) ) ;
                if( trystrtoint( SL, Message_Class ) ) then
                begin
                    if( ( Message_Class >= 0 ) and ( Message_Class <= 22 ) ) then // Valid class
                    begin
                        if( not Classes[ Message_Class ] ) then
                        begin
                            continue ;
                        end ;
                    end ;
                end ;
            end ;

            SL := lowercase( S ) ;
            if( SL = 'log' ) then
            begin
                if( F = nil ) then
                begin
                    Logfile_Name := 'SYS$MANAGER:OPERATOR.LOG' ;
                    S := Get_Symbol( 'OPC$LOGFILE_NAME' ) ;
                    if( S <> '' ) then
                    begin
                        Logfile_Name := S ;
                    end ;
                    F := Open_Binary_File( Logfile_Name, 
                        FAB_V_GET or FAB_V_PUT or FAB_V_SUP or FAB_V_CIF ) ;
                    if( F = nil ) then
                    begin
                        Tell_Operators( BRK_C_OPCOM, 'OPCOM failed to open log file ' + 
                            Logfile_Name ) ;
                        Tell_Operators( BRK_C_OPCOM, LIB_Get_Exception_Text( 0, Open_Error ) ) ;
                    end ;
                end ;
            end else
            if( SL = 'nolog' ) then
            begin
                if( Logfile_Name <> '' ) then
                begin
                    Logfile_Name := '' ;
                    F.Close ;
                    F := nil ;
                end ;
            end else

            if( copy( SL, 1, 7 ) = 'enabled' ) then
            begin
                I := pos( '=', SL ) ;
                SL := trim( copy( SL, I + 1, length( SL ) ) ) ;
                I := pos( ':', SL ) ;
                S := copy( SL, 1, I ) ;
                SL := copy( SL, I + 1, length( SL ) ) ;
                Term := Find_Term( S ) ;
                if( Term = nil ) then
                begin
                    Term := TTerm.Create ;
                    Terms.Add( Term ) ;
                end ;
                if( SL = '' ) then
                begin
                    fillchar( Term.Classes, sizeof( Term.Classes ), -1 ) ;
                end else
                begin
                    Parse_Classes( SL, Term.Classes ) ;
                end ;
            end else
            if( copy( SL, 1, 8 ) = 'disabled' ) then
            begin
                I := pos( '=', SL ) ;
                SL := trim( copy( SL, I + 1, length( SL ) ) ) ;
                I := pos( ':', SL ) ;
                S := copy( SL, 1, I ) ;
                SL := copy( SL, I + 1, length( SL ) ) ;
                Term := Find_Term( S ) ;
                if( Term <> nil ) then // Terminal is an operator
                begin
                    if( SL = '' ) then // Disabling all
                    begin
                        Terms.Remove( Term ) ;
                        Term.Free ;
                    end else
                    begin
                        Parse_Classes( SL, Disabled ) ;
                        for I := 0 to 22 do
                        begin
                            Term.Classes[ I ] := False ;
                        end ;
                    end ;
                end ;
            end ;
        end ; // if( E <> 0 )
    end ; // while( true )
end ; // Run

    function Tell_Operators( Message_Class : integer ; const S : string ) : integer ;

    var I : integer ;

    begin
        Result := 0 ;
        for I := 0 to Terms.Count - 1 do
        begin
            Term := TTerm( Terms[ I ] ) ;
            if( ( Message_Class = BRK_C_OPCOM ) or ( Term.Classes[ Message_Class ] ) ) then
            begin
                Set_String( Term.Name, SRB ) ;
                Set_String( '%%%%%%%%%%% OPCOM ' + ASCTIM( 0 ) + ' %%%%%%%%%%%', Msg ) ;
                Result := SYS_BRKTHRUW( 0, int64( @Msg ), int64( @SRB ), BRK_C_DEVICE,
                    int64( @IOSB ), 0, 0, BRK_C_GENERAL, 5, 0, 0 ) ;
                Set_String( S, Msg ) ;
                Result := SYS_BRKTHRUW( 0, int64( @Msg ), int64( @SRB ), BRK_C_DEVICE,
                    int64( @IOSB ), 0, 0, BRK_C_GENERAL, 5, 0, 0 ) ;
            end ;
        end ;
    end ;

procedure Parse_Classes( S : string ; var Classes : TClasses ) ;

var C : string ;
    I : integer ;

begin
    while( S <> '' ) do // Iterate through classes
    begin
        I := pos( ',', S + ',' ) ;
        C := copy( S, 1, I - 1 ) ;
        S := copy( S, I + 1, length( S ) ) ;
        if( C <> '' ) then // Ignore nulls (,,)
        begin
            I := Class_Index( C ) ;
            if( I = -1 ) then // Invalid class
            begin
                fillchar( Classes, sizeof( Classes ), -1 ) ; // Enable all classes
                break ;
            end ;
            Classes[ I ] := True ;
        end ;
    end ;
end ;

function Class_Index( S : string ) : integer ;

begin
    Result := -1 ;
    S := lowercase( S ) ;
    if( S = 'general' ) then
    begin
        Result := BRK_C_GENERAL ;
    end else
    if( S = 'phone' ) then
    begin
        Result :=  BRK_C_PHONE;
    end else
    if( S = 'mail' ) then
    begin
        Result := BRK_C_MAIL ;
    end else
    if( ( S = 'ucl' ) or ( S = 'dcl' ) ) then
    begin
        Result := BRK_C_UCL ;
    end else
    if( S = 'queue' ) then
    begin
        Result := BRK_C_QUEUE ;
    end else
    if( S = 'shutdown' ) then
    begin
        Result := BRK_C_SHUTDOWN ;
    end else
    if( S = 'urgent' ) then
    begin
        Result := BRK_C_URGENT ;
    end else
    if( S = 'user1' ) then
    begin
        Result := BRK_C_USER1 ;
    end else
    if( S = 'user2' ) then
    begin
        Result := BRK_C_USER2 ;
    end else
    if( S = 'user3' ) then
    begin
        Result := BRK_C_USER3 ;
    end else
    if( S = 'user4' ) then
    begin
        Result := BRK_C_USER4 ;
    end else
    if( S = 'user5' ) then
    begin
        Result := BRK_C_USER5 ;
    end else
    if( S = 'user6' ) then
    begin
        Result := BRK_C_USER6 ;
    end else
    if( S = 'user7' ) then
    begin
        Result := BRK_C_USER7 ;
    end else
    if( S = 'user8' ) then
    begin
        Result := BRK_C_USER8 ;
    end else
    if( S = 'user9' ) then
    begin
        Result := BRK_C_USER9 ;
    end else
    if( S = 'user10' ) then
    begin
        Result := BRK_C_USER10 ;
    end else
    if( S = 'user11' ) then
    begin
        Result := BRK_C_USER11 ;
    end else
    if( S = 'user12' ) then
    begin
        Result := BRK_C_USER12 ;
    end else
    if( S = 'user13' ) then
    begin
        Result := BRK_C_USER13 ;
    end else
    if( S = 'user14' ) then
    begin
        Result := BRK_C_USER14 ;
    end else
    if( S = 'user15' ) then
    begin
        Result := BRK_C_USER15 ;
    end else
    if( S = 'user16' ) then
    begin
        Result := BRK_C_USER16 ;
    end ;
end ; // Class_Index


function Class_Name( I : integer ) : string ;

begin
    Result := '' ;
    case I of
        BRK_C_GENERAL : Result := 'general' ;
        BRK_C_PHONE : Result := 'phone' ;
        BRK_C_MAIL : Result := 'mail' ;
        BRK_C_UCL : Result := 'ucl' ;
        BRK_C_QUEUE : Result := 'queue' ;
        BRK_C_SHUTDOWN : Result := 'shutdown' ;
        BRK_C_URGENT : Result := 'urgent' ;
        BRK_C_USER1 : Result := 'user1' ;
        BRK_C_USER2 : Result := 'user2' ;
        BRK_C_USER3 : Result := 'user3' ;
        BRK_C_USER4 : Result := 'user4' ;
        BRK_C_USER5 : Result := 'user5' ;
        BRK_C_USER6 : Result := 'user6' ;
        BRK_C_USER7 : Result := 'user7' ;
        BRK_C_USER8 : Result := 'user8' ;
        BRK_C_USER9 : Result := 'user9' ;
        BRK_C_USER10 : Result := 'user10' ;
        BRK_C_USER11 : Result := 'user11' ;
        BRK_C_USER12 : Result := 'user12' ;
        BRK_C_USER13 : Result := 'user13' ;
        BRK_C_USER14 : Result := 'user14' ;
        BRK_C_USER15 : Result := 'user15' ;
        BRK_C_USER16 : Result := 'user16' ;
    end ;
end ; // Class_Name

function Normalize_Filename( S : string ) : string ;

var Node, Access, Secondary_Node, Device, Path, Name, Extension, Version : string ;

begin
    Parse_Filename( S,
        Node, Access, Secondary_Node, Device, Path, Name, Extension, Version ) ;
    S := Device + Path + '\' + Name + '.' + Extension ;
    if( Version <> '' ) then
    begin
        S := S + ';' + Version ;
    end ;
    if( Node <> '' ) then
    begin
        S := Node + '::' + S ;
    end ;
    Result := S ;
end ;

In the next article, we will look at the system services that support mailboxes.