AUTHORIZE utility, Reporting

In the last article, we looked at some of the Authorize commands. In this article we will cover the reporting code used by the SHOW and LIST commands. Because these commands are roughly the same, differing only in minor ways, we will place all of the support in a single routine which will alter its behavior slightly, depending upon various options.

function Show_Report( Target, Output : string ) : integer ;

var F : TCOM_UOS_File ;

    procedure Do_Write( const S : string ) ;

    begin
        if( F <> nil ) then
        begin
            F.Writeln( PChar( S ) ) ;
        end else
        begin
            LIB_Put_Output( S + CRLF ) ;
        end ;
    end ; // Show_Report.Do_Write

This function outputs information for the specified user (Target) to the specified destination device (Output) - either sys$output or a file. The local Do_Write function outputs a single line of text. If F is set, the text is written to that file, otherwise it goes to the default output device.

var S, T : integer ;
    Temp : string ;
    U : TUser ;

    procedure Write_Privs( Privileges : int64 ) ;

    var I, I1 : int64 ;
        S, Temp : string ;
        X : integer ;

    begin
        Temp := '' ;
        I := 0 ;
        while( I < 62 ) do
        begin
            I1 := 1 ;
            I1 := I1 shl I ; // Have to do this in 2 steps or shift is done as 32-bit instead of 64-bit
            if( ( Privileges and I1 ) <> 0 ) then
            begin
                S := Privileges_To_String( I1 ) ;
                if( S <> '' ) then
                begin
                    X := pos( ',', S ) ; // For synonym privileges, which would show up as multiple items
                    S := copy( S, X + 1, length( S ) ) ;
                    S := S + Space( 11 - length( S ) ) ;
                    Temp := Temp + S ;
                    if( length( Temp ) > 65 ) then
                    begin
                        Do_Write( '  ' + Temp ) ;
                        Temp := '' ;
                    end ;
                end ;
            end ;
            inc( I ) ;
        end ; // while( I < 62 )
        if( Temp <> '' ) then
        begin
            Do_Write( '  ' + Temp ) ;
        end ;
    end ; // Show_Report.Write_Privs

Write_Privs is used to write out a list of privileges, in a columnar format (if the privileges don't fit on a single line). The privilege mask to display to the user is passed to the function and a user-readable list is output. The width is assumed to be less than 80 columns, since we don't know how wide the output device will be if the report is output to a file and then printed or viewed.

One thing of note is the line that does the left shift (shl). This is a workaround for the compiler which would do a 32-bit shift if we wrote:
I1 := 1 shl I;
By doing it in two steps, the compiler does a 64-bit shift.

    procedure Add_Flag( Flags, I : integer ; FValue : string ; var Value : string ) ;

    begin
        if( ( Flags and I ) <> 0 ) then
        begin
            if( Value <> '' ) then
            begin
                Value := Value + ',' ;
            end ;
            Value := Value + FValue ;
        end ;
    end ; // Show_Report.Add_Flag

This function is used to create a comma-delimited list of values, modifying the passed Value string which allows the function to be called multiple times to build up a single output string.

var A : string ;
    Access : TUAF_Access ;
    Count, UIC : integer ;
    I : integer ;
    This_Account : string ;
    Access_SL : TStringList ;
    Batch_SL : TStringList ;
    Interactive_SL : TStringList ;
    Network_SL : TStringList ;
    Remote_SL : TStringList ;
    Dialup_SL : TStringList ;

begin // Show_Report
    // Setup...
    Result := 0 ;
    F := nil ;
    if( Output <> '' ) then
    begin
        F := Open_Binary_File( Output, FM_RW or FAB_V_CIF ) ;
        if( F.IO_Error <> nil ) then
        begin
            UUI.Show_Error( F.IO_Error.Get_Error, F.IO_Error.Error_Text( S, T ) ) ;
            F.Free ;
            exit ;
        end ;
    end ;
    Target := lowercase( Target ) ;
    if( Full ) then
    begin
        Brief := False ;
    end ;

Now to the main code of the Show_Report function. We start by seeing if an output file has been passed. If so, we open that file for output (creating it if it doesn't exist). If there is an error opening/creating it, we show the error and exit. If no file was passed (Output is null), F is set to nil.

We also normalize the target user to lowercase, and make sure that if both the /FULL and /BRIEF flags were specified, we clear the Brief flag. That is, /FULL overrides /BRIEF.

    if( Brief ) then
    begin
        Do_Write( '         Owner           Username        UIC      Account  Pri Directory' ) ;
    end ;

    // Show report...
    Count := 0 ;
    for UIC := 0 to Max_UIC do
    begin
        U := Get_User( UIC ) ;
        if( U <> nil ) then
        begin
            This_Account := Name_From_UIC( UIC ) ;

If we are displaying a brief list, we output a heading. In all cases, we iterate through all the UICs from 0 to the maximum UIC (Max_UIC). Each time through the loop, we get the user for the UIC. If a nil is returned, that UIC is not in use and we skip to the next one. Otherwise, we get the username from the UIC.

            if( WC_Match( Target, lowercase( This_Account ), TT_UTF8 ) ) then
            begin
                inc( Count ) ;
                if( Brief ) then
                begin
                    Temp := U.Owner_Name ;
                    Temp := Temp + Space( 25 - length( Temp ) ) + This_Account ;
                    Temp := Temp + Space( 41 - length( Temp ) ) + inttostr( U.UIC ) ;
                    Temp := Temp + Space( 50 - length( Temp ) ) + U.Name ;
                    Temp := Temp + Space( 59 - length( Temp ) ) + inttostr( U.Rec.Priority ) ;
                    Temp := Temp + Space( 63 - length( Temp ) ) + U.Home ;
                    Do_Write( Temp ) ;
                end else

Because wildcards can be used for the user name, we use a wilcard match to see if the name for the current UIC matches the specified name. This will work if the target is a wildcard or not. Note that we increment the Count value for each match that we find. If we are doing a brief report, we build up a line for this user with things spaced to form columns that correspond to the heading.

                begin
                    // Show full report...
                    Do_Write( 'Username: ' + This_Account + Space( 30 - length( Target) ) + 
                        ' Owner: ' + U.Owner_Name ) ;
                    Do_Write( 'Account: ' + U.Name + Space( 31 - length( U.Name ) ) + 
                        ' UIC: ' + inttostr( U.UIC ) ) ;
                    Do_Write( 'Shell: ' + U.Shell + Space( 33 - length( U.Shell ) ) + ' ' ) ; 
                    // TODO:Tables
                    Do_Write( 'Default: ' + U.Home ) ;
                    Temp := '' ;
                    Add_Flag( U.Flags, UAI_V_AUDIT, 'Audit', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_AUTOLOGIN, 'Autologin', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_CAPTIVE, 'Captive', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DEFCLI, 'DefCLI', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISCTLY, 'DisCTLY', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISIMAGE, 'Disimage', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISMAIL, 'Dismail', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISNEWMAIL, 'Disnewmail', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISRECONNECT, 'Disreconnect', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISREPORT, 'Disreport', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISACNT, 'Disuser', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_DISWELCOME, 'Diswelcme', Temp ) ;
                    Add_Flag( U.Flags, UAI_V_RESTRICTED, 'Restricted', Temp ) ;
                    Do_Write( 'Flags: ' + Temp ) ;

On the other hand, if we are doing a full report, there is much more work to be done. We write out various pieces of information. For now, we don't display tables (see the TODO). Next, we build up a string of account flags using the above-described Add_Flag function, and then write it out.

                    if( U.Access_Count = 0 ) then
                    begin
                        Do_Write( 'No access restrictions' ) ;
                    end else
                    begin
                        Access_SL := TStringList.Create ;
                        Batch_SL := TStringList.Create ;
                        Interactive_SL := TStringList.Create ;
                        Network_SL := TStringList.Create ;
                        Remote_SL := TStringList.Create ;
                        Dialup_SL := TStringList.Create ;
                        for I := 0 to U.Access_Count - 1 do
                        begin
                            Access := U.Access[ I ] ;
                            A := Access_Day_Name( Access.DOW ) + ', ' + 
                                Minute_To_Text( Access.Starting ) + '-' + Minute_To_Text( Access.Ending ) ;
                            case Access.Typ of
                                UAT_Access : Access_SL.Add( A ) ;
                                UAT_Batch : Batch_SL.Add( A ) ;
                                UAT_Interactive : Interactive_SL.Add( A ) ;
                                UAT_Network : Network_SL.Add( A ) ;
                                UAT_Remote : Remote_SL.Add( A ) ;                                                         
                                UAT_Dialup : Dialup_SL.Add( A ) ;
                            end ;
                        end ;
                        if( Access_SL.Count > 0 ) then
                        begin
                            Do_Write( 'Access allowed:' ) ;
                            for I := 0 to Access_SL.Count - 1 do
                            begin
                                Do_Write( '  ' + Access_SL[ I ] ) ;
                            end ;
                        end ;
                        if( Batch_SL.Count > 0 ) then
                        begin
                            Do_Write( 'Batch allowed:' ) ;
                            for I := 0 to Batch_SL.Count - 1 do
                            begin
                                Do_Write( '  ' + Batch_SL[ I ] ) ;
                            end ;
                        end ;
                        if( Interactive_SL.Count > 0 ) then
                        begin
                            Do_Write( 'Interactive allowed:' ) ;
                            for I := 0 to Interactive_SL.Count - 1 do
                            begin
                                Do_Write( '  ' + Interactive_SL[ I ] ) ;
                            end ;
                        end ;
                        if( Network_SL.Count > 0 ) then
                        begin
                            Do_Write( 'Network allowed:' ) ;
                            for I := 0 to Network_SL.Count - 1 do
                            begin
                                Do_Write( '  ' + Network_SL[ I ] ) ;
                            end ;
                        end ;
                        if( Remote_SL.Count > 0 ) then
                        begin
                            Do_Write( 'Remote allowed:' ) ;
                            for I := 0 to Remote_SL.Count - 1 do
                            begin
                                Do_Write( '  ' + Remote_SL[ I ] ) ;
                            end ;
                        end ;
                        if( Dialup_SL.Count > 0 ) then
                        begin
                            Do_Write( 'Dialup allowed:' ) ;
                            for I := 0 to Dialup_SL.Count - 1 do
                            begin
                                Do_Write( '  ' + Dialup_SL[ I ] ) ;
                            end ;
                        end ;
                        Access_SL.Free ;
                        Batch_SL.Free ;
                        Interactive_SL.Free ;
                        Network_SL.Free ;
                        Remote_SL.Free ;
                        Dialup_SL.Free ;
                    end ;

Next we display access restrictions. There are five specific types of access, plus the general access restrictions. First we create six string lists, one for each of those six categories. Then we loop through the access records of the user, adding the human-readable access description to the appropriate string list. Next we go through each of the possible categories, and output the information for that category, if any. When done, we dispose of the string lists.

                    Temp := '(none)' ;
                    if( U.Expiration > 0 ) then
                    begin
                        Temp := ASCTIM( U.Expiration ) ;
                    end ;
                    Do_Write( 'Expiration: ' + Space( 28 - length( Temp ) ) + 
                        ' Login Fails: ' + inttostr( U.Login_Failures ) ) ;
                    if( U.Last_Interactive_Login = 0 ) then
                    begin
                        Temp := '(none) (interactive)' ;
                    end else
                    begin
                        Temp := ASCTIM( U.Last_Interactive_Login ) + ' (interactive)' ;
                    end ;
                    Temp := 'Last Login: ' + Temp + Space( 28 - length( Temp ) ) ;
                    if( U.Last_Noninteractive_Login = 0 ) then
                    begin
                        Temp := Temp + ' (none)' ;
                    end else
                    begin
                        Temp := Temp + ' ' + ASCTIM( U.Last_Interactive_Login ) ;
                    end ;
                    Do_Write( Temp + ' (interactive)' ) ;

Next we display date-related values for account expiration and last logins, showing either the date/time in user-readable form or else "(none)" if the corresponding timestamp is 0.

                    Do_Write( '' ) ;
                    Temp := 'Maxjobs: ' + inttostr( U.Rec.Quotas.MAXJOBS ) ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' Fillm: ' + 
                        inttostr( U.Rec.Quotas.FILLM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' Bytlm: ' + 
                        inttostr( U.Rec.Quotas.BYTLM ) ;
                    Do_Write( Temp ) ;
                    Temp := 'Maxacctjobs: ' + inttostr( U.Rec.Quotas.MAXACCTJOBS ) ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' Shrfillm: ' + 
                        inttostr( U.Rec.Quotas.SFILLM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' Pbytlm: ' + 
                        inttostr( U.Rec.Quotas.PBYTLM ) ;
                    Do_Write( Temp ) ;
                    Temp := 'Maxdetach: ' + inttostr( U.Rec.Quotas.MAXDETJOBS ) ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' BIOlm: ' +
                        inttostr( U.Rec.Quotas.BIOLM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' JTQuota: ' +
                        inttostr( U.Rec.Quotas.JTQUOTA ) ;
                    Do_Write( Temp ) ;
                    Temp := 'Prclm: ' + inttostr( U.Rec.Quotas.PRCLM ) ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' DIOlm: ' +
                        inttostr( U.Rec.Quotas.DIOLM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' WSdef: ' +
                        inttostr( U.Rec.Quotas.WSDEFAULT ) ;
                    Do_Write( Temp ) ;
                    Temp := 'Prio: ' + inttostr( U.Rec.Priority ) ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' ASTlm: ' +
                        inttostr( U.Rec.Quotas.ASTLM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' WSquo: ' +
                        inttostr( U.Rec.Quotas.WSQUO ) ;
                    Do_Write( Temp ) ;
                    Temp := 'Queprio: ' + inttostr( U.Rec.Priority ) ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' TQElm: ' +
                        inttostr( U.Rec.Quotas.TQELM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' WSextent: ' +
                        inttostr( U.Rec.Quotas.WSEXTENT ) ;
                    Do_Write( Temp ) ;
                    Temp := 'CPU: ' ;
                    if( U.Rec.Quotas.CPUTIM = 0 ) then
                    begin
                        Temp := Temp + ' (none)' ;
                    end else
                    begin
                        Temp := Temp + inttostr( U.Rec.Priority ) ;
                    end ;
                    Temp := Temp + Space( 20 - length( Temp ) ) + ' Enqlm: ' +
                        inttostr( U.Rec.Quotas.ENQLM ) ;
                    Temp := Temp + Space( 40 - length( Temp ) ) + ' Pgflquo: ' +
                        inttostr( U.Rec.Quotas.PGFLQUOTA ) ;
                    Do_Write( Temp ) ;

Next we display account quotas.

                    Do_Write( 'Authorized Privileges:' ) ;
                    Write_Privs( U.Rec.Auth_Privileges ) ;
                    Do_Write( 'Default Privileges:' ) ;
                    Write_Privs( U.Rec.Privileges ) ;
                    Do_Write( '' ) ;
                end ;
            end ;
        end ;
    end ;
    //TODO: Handle /SEARCH, /HIGHLIGHT, and /PAGE
    if( Count = 0 ) then
    begin
        Result := AUTH_BADSPC ;
    end ;

    // Finish up...
    if( F <> nil ) then
    begin
        F.Free ;
    end ;
end ; // Show_Report

Finally, the default and authorized privileges are displayed using the above-described Write_Privs. After we are done executing the loop, we see if the number of matching users is 0. If no users matched, we return an error. And if an output file was specified, we close it.

You may recall from the Authorize documentation in a previous article, that the SHOW command had some additional switches (such as /HIGHLIGHT), which we won't cover until a future article that deals with device-independent formatting (beyond what we already covered with $FAO) - hence the TODO comment.

In the next article, we will continue our coverage of the authorize code.