EOJ and LOGOUT

The EOJ command indicates the "end of job". It immediately ends a batch or interactive session. In essence, this simply logs the process out by running the sys$system:logout.exe program. Here is the user documentation:

EOJ

Marks the end of a batch job.

Format

EOJ

Parameters

None

Description

The EOJ (End Of Job) command marks the end of a batch job submitted via card reader. It is not required. If used in any other context, EOJ logs the process out.

Example

$ EOJ

                    if( Sym = 'eoj' ) then
                    begin
                        Process_EOJ ;
                    end else

This code is added to the Process routine.

font color="black">procedure Process_EOJ ;

begin
    PasStarlet.Run( 'sys$system:logout.exe', '' ) ;
end ;

As mentioned in the documentation, a non-batch job is logged out. However, as it turns out, logging a batch process out is also how we end a UOS batch job. So, it really is the same action in all situations. Logging a process out is done via the LOGOUT CUSP.

LOGOUT

Terminates the process.

Format

LOGOUT

Description

The LOGOUT command must be used to end an interactive session, whether remote or local. Under most circumstances, you can turn the power off at the terminal, hang up a phone/modem, or terminate a network connection without using the LOGOUT command, but the process remains logged in and detached.

Qualifiers

/BRIEF
Displays a brief logout message (process name, date, and time). This is the default.

/FULL
Displays a long logout message including accounting information for the process. This is the default for batch jobs.

/{NO}HANGUP
The default is /NOHANGUP. /HANGUP will disconnect from a dial-up or remote connection.

Example


$ LOGOUT
  GONZALES    logged out at 03-Dec-2021 15:30:26.22

procedure Set_String( var Value : string ; var SRB : TSRB ) ;

begin
    SRB.Buffer := int64( PChar( Value ) ) ; // Symbol name
    SRB.Length := length( Value ) ;
    SRB.Flags := 0 ;
end ;


var Mode : int64 ;
    PrcName : string ;
    PrcNameLen : int64 ;
    LengthA : int64 ;
    Temp : string ;
    ResLen : int64 ;

function Format_Time( Tim : int64 ) : string ;

var SRB : TSRB ;

begin
    if( Tim = 0 ) then
    begin
        Result := '00:00:00.0' ;
        exit ;
    end ;
    LengthA := 0 ;
    Temp := '                ' ;
    set_String( Temp, SRB ) ;
    LIB_SYS_ASCTIM( int64( @LengthA ), int64( @SRB ), Tim, 1 ) ;
    setlength( Temp, LengthA ) ;
    Result := Temp ;
end ;

Now we will look at the code for the LOGOUT program. The above code implements some support routines. Set_String saves us some work. Format_Time simply formats a timestamp. This is needed both to save work but to also handle the case when we want to format a time value of 0. You may recall that if we ask LIB_SYS_ASCTIM to format a timestamp, if we pass 0 for the time, it returns the current timestamp. What we are formatting is an amount of elapsed time.

function Run : int64 ;

var Brief, Full, Disconnect : boolean ;
    Command, Parameter : string ;
    Elapsed, CPU, VPCPU : string ;
    IOSB : TIOSB ;
    itmlst : array[ 0..9 ] of TSYS_Descriptor ;
    OS : POS_UOS ;
    S : string ;

    procedure Set_Item( Index, Code, BufLen, BufAdd, Ret : int64 ) ;

    begin
        itmlst[ Index ].MBO := $FFFF ;
        itmlst[ Index ].MBMO := -1 ;
        itmlst[ Index ].Buffer_Length := BufLen ;
        itmlst[ Index ].Item_Code := Code ;
        itmlst[ Index ].Buffer_Address := BufAdd ;
        if( Ret = 0 ) then
        begin
            Ret := int64( @ResLen ) ;
        end ;
        itmlst[ Index ].Return_Length_Address := Ret ;
    end ;

var Bufio, Dirio, Faults, WSPeak, VirtPeak, CPUtim, VPCPUtim, Logintim, Timestamp, Volumes : int64 ;
    SRB : TSRB ;

begin
    // Setup...
    OS := new( POS_UOS, Init ) ;
    Result := 0 ;
    fillchar( itmlst, sizeof( itmlst ), 0 ) ;

The Run procedure is the main routine for the LOGOUT Commonly Used System Program. We will see this used in all CUSPs. There are several reasons for this. Practically, most CUSPs can be called as routines from other programs, and the standard routine is used to execute the CUSP's features. We will see expanded uses of this in the future. The LOGOUT and LOGIN programs are special cases and have a much more simplified interface. There is no need to call them from other programs. But we will try to make things as consistent as we can across all CUSPs.

The Set_Item local function is simply a way of quickly setting up a descriptor array for a GETJPI call later in the code.

The POS_UOS object is a Pascal interface to UOS, much like PasStarlet, but it is a higher-level interface whereas PasStarlet is a thin wrapper that does little more than convert strings to TSRBs and builds system requests.

    // Parse switches...
    Command := OS^.Command_Line ;
    Brief := False ;
    Full := False ;
    Disconnect := False ;
    if( Parse_Switch( 'B|RIEF', '', Command, Parameter ) = 1 ) then
    begin
        Brief := True ;
        if( Parameter <> '' ) then
        begin
            OS^.outputln( 'Parameter not allowed after /BRIEF' ) ;
            OS.Free ;
            exit ;
        end ;
    end ;
    if( Parse_Switch( 'F|ULL', '', Command, Parameter ) = 1 ) then
    begin
        Full := True ;
        if( Parameter <> '' ) then
        begin
            OS^.outputln( 'Parameter not allowed after /FULL' ) ;
            OS.Free ;
            exit ;
        end ;
    end ;
    case( Parse_Switch( 'H|ANGUP', 'NOH|ANGUP', Command, Parameter ) ) of
        1 : Disconnect := True ;
        2 : Disconnect := False ;
    end ;
    if( Parameter <> '' ) then
    begin
        OS^.outputln( 'Parameter not allowed after /HANGUP or /NOHANGUP' ) ;
        OS.Free ;
        exit ;
    end ;
    S := Next_Switch( Command, Parameter ) ;
    if( S <> '' ) then
    begin
        OS^.outputln( 'Unknown switch: /' + S ) ;
        OS.Free ;
        exit ;
    end ;

This code processes switches. We've reviewed similar code in the past, so we won't linger here. Since the Delphi compiler targets MS Windows, we cannot use the writeln statement to output text. the OS^.outputln serves the purpose for UOS.

    // Get current time...
    LengthA := 0 ;
    setlength( S, 256 ) ;
    Set_String( S, SRB ) ;
    LIB_SYS_ASCTIM( int64( @LengthA ), int64( @SRB ), Timestamp, 0 ) ;
    setlength( S, LengthA ) ;

    // Display default information...
    PrcName := '                ' ;
    PrcNameLen := 0 ;
    Set_Item( 0, JPI_PRCNAM, 16, int64( PChar( PrcName ) ), int64( @PrcNameLen ) ) ;
    Set_Item( 1, JPI_MODE, sizeof( Mode ), int64( @Mode ), 0 ) ;
    SYS_GETJPIW( 0, 0, 0, int64( @itmlst ), int64( @IOSB ), 0, 0 ) ;
    setlength( PrcName, PrcNameLen ) ;
    while( length( PrcName ) < 16 ) do
    begin
        PrcName := PrcName + ' ' ;
    end ;
    if( ( Mode = JPI_K_BATCH ) and ( not Brief ) ) then
    begin
        Full := True ;
    end ;
    OS^.Outputln( '  ' + PrcName + ' Logged out at ' + S ) ;

This code is used to display the brief logout message (which is displayed whether /BRIEF or /FULL is used). We first get the current time and then we use the GETJPI service to obtain the current process name and mode. If /BRIEF wasn't specified and the process is in batch mode, we set the Full flag. Now that we have all the information, we display the entire brief message.

    // Display accounting information...
    if( Full ) then
    begin
        fillchar( itmlst, sizeof( itmlst ), 0 ) ;
        Set_Item( 0, JPI_BUFIO, sizeof( Bufio ), int64( @Bufio ), 0 ) ;
        Set_Item( 1, JPI_DIRIO, sizeof( Dirio ), int64( @Dirio ), 0 ) ;
        Set_Item( 2, JPI_PAGEFLTS, sizeof( Faults ), int64( @Faults ), 0 ) ;
        Set_Item( 3, JPI_WSPEAK, sizeof( WSPeak ), int64( @WSPeak ), 0 ) ;
        Set_Item( 4, JPI_VIRTPEAK, sizeof( VirtPeak ), int64( @VirtPeak ), 0 ) ;
        Set_Item( 5, JPI_CPUTIM, sizeof( CPUtim ), int64( @CPUtim ), 0 ) ;
        Set_Item( 6, JPI_VP_CPUTIM, sizeof( VPCPUtim ), int64( @VPCPUtim ), 0 ) ;
        Set_Item( 7, JPI_LOGINTIM, sizeof( Logintim ), int64( @Logintim ), 0 ) ;
        Set_Item( 8, JPI_VOLUMES, sizeof( Volumes ), int64( @Volumes ), 0 ) ;
        SYS_GETJPIW( 0, 0, 0, int64( @itmlst ), int64( @IOSB ), 0, 0 ) ;
        CPU := Format_Time( CPUTim ) ;
        VPCPU := Format_Time( VPCPUTim ) ;
        Elapsed := Format_Time( LIB_Get_Timestamp - Logintim ) ;

        OS^.Outputln( 'Accounting information:' ) ;
        OS^.Outputln( 'Buffered I/O count: ' + inttostr( Bufio ) + 
            '  Peak working set size: ' + inttostr( WSPeak ) ) ;
        OS^.Outputln( 'Direct I/O count:   ' + inttostr( Dirio ) + 
            '  Peak virtual size: ' + inttostr( VirtPeak ) ) ;
        OS^.Outputln( 'Page faults:        ' + inttostr( Faults ) + 
            '  Mounted volumes: ' + inttostr( Volumes ) ) ;
        OS^.Outputln( 'Charged CPU time:   ' + CPU + 
            '  Elapsed time: ' + Elapsed ) ;
        OS^.Outputln( 'Charged vector CPU time: ' + VPCPU ) ;
    end ;

If accounting information was requested, we use GETJPI to obtain the information and then output it.

    // Kill process...
    SYS_DELPRC() ;
    OS.Free ;
end ; // Run

Finally, we call the SYS_DELPRC service to kill the current process. Once this service executes, no following code executes. However, for the sake of simulators we clean up and exit.

In the next article, we will look at the new system services called in the foregoing code.