In this article, we look at the DISABLE CUSP - the next thing used in our shutdown script. The purpose of the CUSP is to stop autostart queues. This is a larger discussion related to queues, which we will discuss in the future. We only cover this here because it is used during shutdown. There are a couple of points that are necessary to understand what the CUSP is doing.

Queue managers are programs which manage one or more queues. Queues can be print queues for sending print jobs to printers, or batch queues for executing programs. Each queue contains zero, one, or more items (either files to print or scripts to execute) that are processed one at a time, in the order they were added to the queue. Like OPCOM, queue managers run detached and use a mailbox to which commands can be sent. The DISABLE CUSP sends a message to a queue manager to inform it to stop autostart queues.

By default, a UOS system has a single queue manager that manages all print and batch jobs. This defines the SYS$QUEUE_MANAGER symbol as the mailbox which that default queue manager uses to receive commands. Other queue managers can be optionally started with their own mailboxes for communications. Essentially, the name of the queue manager is the name of the symbol containing the mailbox device used by the manager. Now the documentation:

/NAME_OF_MANAGER
Indicates the name of a queue manager whose autostart queues are to be disabled. If omitted, the default queue manager SYS$QUEUE_MANAGER is used.

/ON_NODE=name
Specifies the name of the node on which the queue manager is located, to disable queue managers on other nodes.

/QUEUES
This qualifier is used by default. Specifies that autostart is to be disabled for all queues.

Required Privileges

OPER is required.

Examples

$ DISABLE AUTOSTART/QUEUES Disables all autostart queues for the default system queue manager SYS$QUEUE_MANAGER.

$ DISABLE AUTOSTART/ON=VINCENT In this case, autostart queues for the default system queue manager on the node named VINCENT are disabled.

$ DISABLE AUTOSTART/NAME=MAIN_OFFICE_QUEUE_MANAGER In this case, all autostart queues managed by the queue manager named MAIN_OFFICE_QUEUE_MANAGER are disabled.

const UI =  'object Main:rectangle' + CR +
            '  top = 2' + CR +
            '  object ilabel:label' + CR +
            '    text = "Queue Manager:"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object name:string' + CR +
            '    hint = "Queue name"' + CR +
            '    top = $margin' + CR +
            '    left = ilabel.width + $margin' + CR +
            '  end' + CR +
            '  object olabel:label' + CR +
            '    text = "Node:"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object node:string' + CR +
            '    hint = "Node name"' + CR +
            '    top = $margin' + CR +
            '    left = olabel.width + $margin' + CR +
            '  end' + CR +
            '  object queues:boolean' + CR +
            '    top = $margin' + CR +
            '    left = node.left + node.width + $margin' + CR +
            '  end' + CR +
            'end' ;

This is the UI definition for the DISABLE CUSP.

function Run : int64 ;

var C, Ctx : string ;
    E : int64 ;
    OS : POS_UOS ;

begin
    Result := 0 ;
    OS := new( POS_UOS, Init ) ;
    C := Get_Symbol( 'disable$defaults' ) ;
    Ctx := '' ;
    E := _Disable( PChar( OS^.Command_Line ), PChar( C ), True, Ctx ) ;
    if( E <> 0 ) then
    begin
        OS^.OutputLn( 0, LIB_Get_Exception_Text( 0, E ) ) ;
        if( Ctx <> '' ) then
        begin
            OS^.OutputLn( 0, '    \' + Ctx + '\' ) ;
        end ;
    end ;
    OS.Free ;
    SYS_EXIT( 0 ) ;
end ;

This is the program entry point, which resembles that of most past CUSPs we've looked at.

var Buf : array[ 0..1023 ] of char ;
    BufLen : int64 ;
    IOSB : TIOSB ;

function Get_JPI( PP, Index : int64 ) : string ;

var PP_SYS_Descriptor : array[ 0..1 ] of TSYS_Descriptor ;

begin
    BufLen := sizeof( Buf ) ;
    fillchar( PP_SYS_Descriptor, sizeof( PP_SYS_Descriptor ), 0 ) ;
    PP_SYS_Descriptor[ 0 ].MBO := $FFFF ;
    PP_SYS_Descriptor[ 0 ].MBMO := -1 ;
    PP_SYS_Descriptor[ 0 ].Buffer_Length := sizeof( Buf ) ;
    PP_SYS_Descriptor[ 0 ].Item_Code := Index ;
    PP_SYS_Descriptor[ 0 ].Buffer_Address := integer( @Buf ) ;
    PP_SYS_Descriptor[ 0 ].Return_Length_Address := integer( @BufLen ) ;
    GETJPIW( 0, int64( @PP ), '', integer( @PP_SYS_Descriptor ), integer( @IOSB ), 0, 0 ) ;
    setlength( Result, BufLen ) ;
    move( Buf[ 0 ], PChar( Result )[ 0 ], BufLen ) ;
end ;

This routine has been used in other CUSPs and simply gets a single item of process information.

function _Disable( Command, Defaults : PChar ; Standalone : boolean ;
    var Ctx : string ) : int64 ;

var C, S : string ;
    Component : TUUI_Component ;
    Defaulted : boolean ;
    F : TCOM_UOS_File ;
    P : int64 ;
    Node, Name : string ;
    Priv : int64 ;
    SRB : TSRB ;
    UUI : TUUI ;

begin
    // Setup...
    Result := 0 ;
    Defaulted := False ;
    UUI := TUUI.Create ;
    UUI.Definition := UI ;
    S := Get_JPI( 0, JPI_CURPRIV ) ;
    move( PChar( S )[ 0 ], Priv, sizeof( Priv ) ) ;
    if( ( Priv and OPER ) = 0 ) then
    begin
        Result := UOSErr_Protection_Violation ;
        exit ;
    end ;

    // Prepend command line with defaults...
    P := Switch_Present( Command ) ;
    if( P = 0 ) then
    begin
        P := length( Command ) + 1 ;
    end ;
    C := copy( Command, 1, P - 1 ) + Defaults + copy( Command, P, length( Command ) ) ;
    UUI.Command_Line := PChar( C ) ;

This routine does the work of the CUSP. We set up for processing as we have in previous CUSPs. In our case, we also check that the user has the OPER privilege.

    // Processing...
    if( UUI.Execute( '', Standalone ) ) then
    begin
        S := UUI.Get_Parameter( 'DISABLE', '_What:' )  ;
        if( lowercase( S ) <> 'autostart' ) then
        begin
            Result := IVKEYW ;
            Ctx := S ;
            exit ;
        end ;
        Component := UUI.Get_Component_By_Name( 'node' ) ;
        Node := Component.Text ;
        Component := UUI.Get_Component_By_Name( 'name' ) ;
        Name := Component.Text ;

        if( Name = '' ) then
        begin
            Name := 'SYS$QUEUE_MANAGER' ;
            Defaulted := True ;
        end ;
        //TODO: Handle remote node
        Name := Get_Symbol_Value( 'LNM$PERMANENT_MAILBOX', Name, False, 3 ) ;
        if( Name = '' ) then // No symbol or null value
        begin
            if( not Defaulted ) then
            begin
                Result := JBC_JOBQUEDIS ;
            end ;
            exit ;
        end ;
        Set_String( Name, SRB ) ;
        F := Open_File( int64( @SRB ), FAB_V_PUT ) ;
        if( F = nil ) then
        begin
            Result := JBC_JOBQUEDIS ;
        end else
        begin
            F.Writeln( 'autostart disable' ) ;
            F.Free ;
        end ;
    end ; // if( UUI.Execute )
end ; // _Disable

First we process the UI and then we verify that "DISABLE" is followed by "AUTOSTART". The TODO comment is there to indicate that we are not dealing with clusters at this point. The rest of the code simply translates the queue manager symbol (defaulting to SYS$QUEUE_MANAGER if no name was specified). Then we open the mailbox and write a message to it. We will discuss the queue manager service in the future. If the open fails or the symbol doesn't exist (or is null), we return an error and exit.

In the next article, we will look at the STOP command.