COPY, part 2

In this article we will start to look at the code to implement the COPY CUSP, as documented in the previous article.

const UI =  'object Main:rectangle' + CR +
            '  top = 2' + CR +
            '  object ilabel:label' + CR +
            '    text = "Input file(s):"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object input:string' + CR +
            '    hint = "Input filespec"' + CR +
            '    top = $margin' + CR +
            '    left = ilabel.width + $margin' + CR +
            '    require = "_From:"' + CR +
            '  end' + CR +
            '  object olabel:label' + CR +
            '    text = "Output file(s):"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object output:string' + CR +
            '    hint = "Output filespec"' + CR +
            '    top = $margin' + CR +
            '    left = olabel.width + $margin' + CR +
            '    require = "_To:"' + CR +
            '  end' + CR +
            '  object elabel:label' + CR +
            '    text = "Exclude file(s):"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object exclude:string' + CR +
            '    hint = "Exclusions filespec"' + CR +
            '    top = $margin' + CR +
            '    left = elabel.width + $margin' + CR +
            '  end' + CR +
            '' +
            '  object Options:rectangle' + CR +
            '    object Allocation:integer' + CR +
            '      hint = "Allocation size"' + CR +
            '      text = 0' + CR +
            '    end' + CR +
            '    object Backup:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Check to base selection on last backup time"' + CR +
            '    end' + CR +
            '    object label1:label' + CR +
            '      text = "Before:"' + CR +
            '    end' + CR +
            '    object Before:time' + CR +
            '      text = ""' + CR +
            '      truehint = "When checked, files before the indicated date will be selected"' + CR +
            '      left = label1.left + label1.width' + CR +
            '    end' + CR +
            '    object label2:label' + CR +
            '      text = "Block size:"' + CR +
            '    end' + CR +
            '    object Block_Size:integer' + CR +
            '      hint = "Block size"' + CR +
            '      text = 0' + CR +
            '      left = label2.left + label2.width' + CR +
            '    end' + CR +
            '    object label3:label' + CR +
            '      text = "Owner:"' + CR +
            '    end' + CR +
            '    object By_Owner:string' + CR +
            '      text = ""' + CR +
            '      hint = "User name/UIC"' + CR +
            '      left = label3.left + label3.width' + CR +
            '    end' + CR +
            '    object Concatenate:boolean' + CR +
            '      text = "True"' + CR +
            '      truehint = "Click to concatenate files"' + CR +
            '      falsehint = "Click to copy without concatenation"' + CR +
            '    end' + CR +
            '    object Confirm:boolean' + CR +
            '      text = "false' + CR +
            '      truehint = "Click to confirm each copy"' + CR +
            '      falsehint = "Click to not confirm each copy"' + CR +
            '    end' + CR +
            '    object Contiguous:boolean' + CR +
            '      text = "false"' + CR +
            '      falsehint = "Click to "' + CR +
            '      truehint = "Click to "' + CR +
            '    end' + CR +
            '    object Created:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Check to base selection on file creation date"' + CR +
            '    end' + CR +
            '    object Expired:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Check to base selection on file expiration date"' + CR +
            '    end' + CR +
            '    object label4:label' + CR +
            '      text = "Extension:"' + CR +
            '    end' + CR +
            '    object Extension:integer' + CR +
            '      hint = "Extension size"' + CR +
            '      text = 0' + CR +
            '      left = label4.left + label4.width' + CR +
            '    end' + CR +
            '    object Log:boolean' + CR +
            '      text = "false"' + CR +
            '      falsehint = "Click to display copy operations"' + CR +
            '      truehint = "Click to disable display of copy operations"' + CR +
            '    end' + CR +
            '    object Modified:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Check to base selection on file modification date"' + CR +
            '    end' + CR +
            '    object label5:label' + CR +
            '      text = "File protections:"' + CR +
            '    end' + CR +
            '    object Protection:string' + CR +
            '      text = "false"' + CR +
            '      hint = "Protection for output file(s)"' + CR +
            '      left = label5.left + label5.wigth' + CR +
            '    end' + CR +
            '    object Read_check:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Select to verify read operations"' + CR +
            '    end' + CR +
            '    object Replace:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Select to replace existing files"' + CR +
            '    end' + CR +
            '    object label6:label' + CR +
            '      text = "Since:"' + CR +
            '    end' + CR +
            '    object Since:time' + CR +
            '      text = ""' + CR +
            '      truehint = "When checked, files since the indicated date will be selected"' + CR +
            '      inverse=Numeric_Keypad' + CR +
            '      left = label6.left + label6.width' + CR +
            '    end' + CR +
            '    object label7:label' + CR +
            '      text = "Style:"' + CR +
            '    end' + CR +
            '    object Style:list' + CR +
            '      left = label2.width + $margin' + CR +
            '      hint = "File name format on log"' + CR +
            '      list = "Condensed", "Expanded"' + CR +
            '      text = "Condensed"' + CR +
            '      type = constrained' + CR +
            '      left = label7.left + label7.width' + CR +
            '    end' + CR +
            '    object Symlink:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Select to copy files instead of links"' + CR +
            '    end' + CR +
            '    object Truncate:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Select to truncate files to logical EOF"' + CR +
            '    end' + CR +
            '    object Version:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Select to treat files as versioned"' + CR +
            '    end' + CR +
            '    object label8:label' + CR +
            '      text = "Volume:"' + CR +
            '    end' + CR +
            '    object Volume:integer' + CR +
            '      hint = "Volume"' + CR +
            '      text = 0' + CR +
            '      left = label8.left + label8.width' + CR +
            '    end' + CR +
            '    object Write_check:boolean' + CR +
            '      text = "false"' + CR +
            '      hint = "Select to verify write operations"' + CR +
            '    end' + CR +
            'end' ;

This is the UI definition for the COPY CUSP.

function Run : int64 ;

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

begin
    OS := new( POS_UOS, Init ) ;
    C := LIB_Get_Symbol( 'copy$defaults' ) ;
    E := _Copy( PChar( OS^.Command_Line ), PChar( C ), True ) ;
    if( E <> 0 ) then
    begin
        OS^.OutputLn( 0, LIB_Get_Exception_Text( 0, E ) ) ;
    end ;
    OS.Free ;
    SYS_EXIT( 0 ) ;
end ;

This is the run routine for COPY. It is similar to past examples, so we won't say anything further.

type TOperation = ( Op_Copy, Op_Concatenate, Op_Contiguous, Op_Noncontiguous ) ;
type TFile_Date_Match = ( Date_Backup, Date_Created, Date_Expired, Date_Modified ) ;
type TFile_Date_Mode = ( Date_None, Date_Before, Date_Since ) ;
type TStyle = ( Style_None, Style_Condensed, Style_Expanded ) ;

function _Copy( Command, Defaults : PChar ; Standalone : boolean ) : int64 ;

var Allocation_Size, Block_Size, Extension_Size, Owner, Protection, Volume : int64 ;
    Comparison_Time : int64 ; // Timestamp to use for date comparisons
    Priv : int64 ;
    Buffer : array[ 0..8191 ] of byte ;
    C, S, O, O1, S1 : string ;
    Component : TUUI_Component ;
    Confirm, Contiguous, Log, Overlay, Read_Check, Write_Check, Replace : boolean ;
    Count : int64 ;
    D : string ;
    Date_Match_Count : integer ;
    DefDev : string ;
    DefDir : string ;
    DefProt : int64 ;
    Descriptors : array[ 0..1 ] of TSYS_Descriptor ;
    E : int64 ;
    Err : int64 ;
    F, OutFile : TCOM_UOS_File ;
    File_Date_Match : TFile_Date_Match ;
    File_Date_Mode : TFile_Date_Mode ;
    File_Time : int64 ; // File date for comparison
    I, L, P : int64 ;
    IFlags, OFlags : int64 ; // Optional input/output flags
    Increment : integer ;
    Index, Index1 : integer ;
    Inputs, Exclusions : TStringList ;
    Input_Wildcards : boolean ;
    Len : int64 ;
    Node, Access, Secondary_Node, Device, _Out, Path, Name, Extension, Version : string ;
    Operation : TOperation ;
    OS : POS_UOS ;
    Output : string ;
    Protection_Mask : int64 ;
    Search_Context : int64 ;
    Skip_File : boolean ;
    Style : TStyle ;
    Symlink, Truncate, Use_Protection, Versions : boolean ;
    UUI : TUUI ;

begin
    // Setup...
    Result := 0 ;
    UUI := TUUI.Create ;
    UUI.Definition := UI ;
    DefDir := GETDDIR ;
    DefDev := LIB_Get_Symbol( 'sys$disk:' ) ;
    S := Get_JPI( 0, JPI_CURPRIV ) ;
    move( PChar( S )[ 0 ], Priv, sizeof( Priv ) ) ;
    Increment := 0 ;
    Protection_Mask := $FFFF ; // Assume nothing specified by user
    DefProt := Get_Default_File_Protection( 0 ) ;
    fillchar( Buffer, sizeof( Buffer ), 0 ) ;

    // 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 ) + D + copy( Command, P, length( Command ) ) ;
    UUI.Command_Line := PChar( C ) ;

This is the code that does the copy operation. We start with setting up the UUI, initializing variables, getting the default device and directory, getting the default file protection, and the user's current privileges.

    // Processing...
    if( UUI.Execute( '', Standalone ) ) then
    begin
        // Parse input files...
        Input_Wildcards := False ;
        Component := UUI.Get_Component_By_Name( 'Input' ) ;
        S := Component.Text ;
        Inputs := TStringList.Create ;
        Exclusions := TStringList.Create ;
        try
            while( S <> '' ) do
            begin
                C := trim( Parse_Parameter( ',', S, 0, '+' ) ) ;
                if( C <> '' ) then
                begin
                    Parse_Filename( C, Node, Access, Secondary_Node, Device, Path,
                        Name, Extension, Version ) ;
                    if( Device = '' ) then
                    begin
                        Device := DefDev ;
                    end ;
                    if( Path = '' ) then
                    begin
                        Path := DefDir ;
                    end ;
                    C := Node + Access + Device + Path + Name + Extension + Version ;
                    Inputs.Add( C ) ;
                    if( pos( '*', C ) + pos( '?', C ) >= Low_String_Index ) then
                    begin
                        Input_Wildcards := True ;
                    end ;
                end ;
            end ;
            if( Inputs.Count = 0 ) then // No input files specified
            begin
                Result := COPY_INPREQ ;
                exit ;
            end ;

Now we execute the UUI and, assuming no errors, we begin to process the parameters and options. First, we parse the list of input files. The filespecs in the list can be delimited by either commas (,) or plus signs (+). For each filespec in the list, we default the device and path if they are not specified. We add each updated filespec to the Inputs list. We also set a flag if any wildcards are detected in any of the specifications. If no inputs are specified, we exit with an error.

            // Parse output file...
            Component := UUI.Get_Component_By_Name( 'Output' ) ;
            Output := trim( Component.Text ) ;
            if( Output = '' ) then
            begin
                Result := COPY_OUTREQ ;
                exit ;
            end ;
            Parse_Filename( Output, Node, Access, Secondary_Node, Device, Path,
                Name, Extension, Version ) ;
            if( Name = '' ) then
            begin
                Name := '*' ;
            end ;
            if( Extension = '' ) then
            begin
                Extension := '*' ;
            end ;
            if( Device = '' ) then
            begin
                Device := DefDev ;
            end ;
            if( Path = '' ) then
            begin
                Path := DefDir ;
            end ;
            Output := Node + Access + Device + Path + Name + Extension + Version ;
            if( pos( '?', Output ) > 0 ) then
            begin
                Result := COPY_IVWILD ;
                exit ;
            end ;
            if( Invalid_Wildcard( Node ) or Invalid_Wildcard( Access ) or
                Invalid_Wildcard( Device ) or Invalid_Wildcard( Path ) or
                Invalid_Wildcard( Name ) or Invalid_Wildcard( Extension ) or
                Invalid_Wildcard( Version ) ) then
            begin
                Result := COPY_IVWILD ;
                exit ;
            end ;

Next we process the output file specification. Likewise with the input files, we default the device and path, if they aren't specified. VMS COPY only supports output file specification wildcards of *, so we exit with an error if the ? wildcard is found. Also the * wildcard, if used, must be the only thing in the field. That is, something like "A*B" is not valid. Now, I spent some time considering enhancing this feature so that such a wildcard specification would be allowed. However, I decided against this for three reasons: 1) it is spec creep, 2) it isn't essential, and 3) the resulting output filenames from using this kind of specification in both input and output specifications might be confusing to the average non-technical user. Perhaps I'll revist this in the future because it does have some utility. For instance, one could both mass copy and rename files from something like "APPLE*" to "PEAR*". However, we're still faced with the third problem of confusing users. For instance, what would one expect from the command "COPY A?B*C X*"? Of course, we could come up with a consistent and predictable result, but would the average home user have a clue? So, Invalid_Wildcard checks for valid file specification fields. If the Name or Extension are null, we set them to "*".

            // Determine what type of operation we are performing...
            Operation := Op_Copy ;
            Component := UUI.Get_Component_By_Name( 'Concatenate' ) ;
            if( Component.UUI ) then // Specified by user
            begin
                if( Component.Text = 'true' ) then
                begin
                    if( ( Inputs.Count > 1 ) or Input_Wildcards ) then
                    // Concatenation only makes sense if there are multiple inputs
                    begin
                        Operation := Op_Concatenate ;
                    end ;
                end ;
            end else
            begin
                // User didn't specify /CONCATENATE or /NOCONCATENATE
                if(
                    ( Inputs.Count > 1 )
                    and
                    ( pos( '*', Output ) + pos( '?', Output ) < Low_String_Index )
                  ) then
                begin
                    { No wildcard output with multiuple input files is normally a
                      concatenation operation. }
                    Operation := Op_Concatenate ;
                end ;
            end ;
            if(
                ( Inputs.Count = 1 ) // Single input
                and
                ( pos( '*', Output ) + pos( '?', Output ) < Low_String_Index ) // No wildcard
                and
                ( lowercase( Output ) = lowercase( Inputs[ 0 ] ) ) // Same input and output
              ) then
            begin
                Component := UUI.Get_Component_By_Name( 'Contiguous' ) ;
                if( Component.UUI ) then // Specified by user
                begin
                    if( Component.Text = 'true' ) then
                    begin
                        Operation := Op_Contiguous ;
                    end else
                    begin
                        Operation := Op_Noncontiguous ;
                    end ;
                end ;
            end ;

Now we determine which type of operation we are going to perform. Essentially there are four types of operations that COPY performs. By determining this ahead of time, it makes the following code a little simpler. The following are the four operations:

Copy	Copy files
Append	Append multiple files into one
Contiguous	Mark an existing file as contiguous
Noncontiguous	Mark an existing file as noncontiguous

This code determines the operation in accordance with the documentation we covered in the previous article.

            // Determine selection type...
            Date_Match_Count := 0 ;
            File_Date_Match := Date_Created ; // Default is creation date
            Component := UUI.Get_Component_By_Name( 'Backup' ) ;
            if( Component.Text = 'true' ) then
            begin
                inc( Date_Match_Count ) ;
                File_Date_Match := Date_Backup ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Created' ) ;
            if( Component.Text = 'true' ) then
            begin
                inc( Date_Match_Count ) ;
                File_Date_Match := Date_Created ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Expired' ) ;
            if( Component.Text = 'true' ) then
            begin
                inc( Date_Match_Count ) ;
                File_Date_Match := Date_Expired ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Modified' ) ;
            if( Component.Text = 'true' ) then
            begin
                inc( Date_Match_Count ) ;
                File_Date_Match := Date_Modified ;
            end ;
            if( Date_Match_Count > 1 ) then
            begin
                Result := COPY_CONFQUAL ;
                exit ;
            end ;

            // Determine selection mode...
            Date_Match_Count := 0 ;
            File_Date_Mode := Date_None ;
            S := '' ;
            Component := UUI.Get_Component_By_Name( 'Since' ) ;
            if( Component.UUI ) then
            begin
                inc( Date_Match_Count ) ;
                File_Date_Mode := Date_Since ;
                S := 'TODAY' ;
                if( Component.Text <> '' ) then
                begin
                    S := Component.Text ;
                end ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Before' ) ;
            if( Component.UUI) then
            begin
                inc( Date_Match_Count ) ;
                File_Date_Mode := Date_Before ;
                S := 'TODAY' ;
                if( Component.Text <> '' ) then
                begin
                    S := Component.Text ;
                end ;
            end ;
            if( Date_Match_Count > 1 ) then
            begin
                Result := COPY_CONFQUAL ;
                exit ;
            end ;
            if( File_Date_Mode <> Date_None ) then
            begin
                S := lowercase( S ) ;
                if( S = 'boot' ) then
                begin
                    S := Get_SYI( SYI_BOOTTIME, '', 0 ) ;
                    move( PChar( S )[ 0 ], Comparison_Time, sizeof( Comparison_Time ) ) ;
                end else
                if( S = 'login' ) then
                begin
                end else
                if( S = 'job_login' ) then
                begin
                    P := Parent_PID( 0 ) ;
                    S := Get_JPI( P, JPI_LOGINTIM ) ;
                    move( PChar( S )[ 0 ], Comparison_Time, sizeof( Comparison_Time ) ) ;
                end else
                begin
                   Comparison_Time := BINTIM( S ) ;
                   if( Comparison_Time = 0 ) then
                   begin
                       Result := COPY_INVQUAVAL ;
                       exit ;
                   end ;
                end ;
            end ;

Next, we determine what date comparisons are to be done (if any). We exit with an error if there are conflicting options. Comparison_Time is the timestamp to compare against and File_Date_Match indicates which file timestamp to use in the comparison.

            // Get exclusions...
            Component := UUI.Get_Component_By_Name( 'Exclude' ) ;
            C := Component.Text ;
            if( C <> '' ) then
            begin
                // Remove optional parentheses...
                if( copy( C, 1, 1 ) = '(' ) then
                begin
                    C := copy( C, 2, length( C ) ) ;
                    if( copy( C, length( C ), 1 ) = ')' ) then
                    begin
                        setlength( C, length( C ) - 1 ) ;
                    end ;
                end ;
                while( C <> '' ) do
                begin
                    S := Parse_Parameter( ',', C ) ;
                    Exclusions.Add( trim( S ) ) ;
                end ;
            end ;

Next we parse the list of files to exclude. First we trim any parentheses, and then parse each filespec, delimited by commas, into the Exclusions list.

            // Get options...
            Component := UUI.Get_Component_By_Name( 'Allocation' ) ;
            if( Component.Text <> '' ) then
            begin
                Allocation_Size := strtoint( Component.Text ) ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Block_size' ) ;
            if( Component.Text <> '' ) then
            begin
                Block_Size := strtoint( Component.Text ) ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Extension' ) ;
            if( Component.Text <> '' ) then
            begin
                Extension_Size := strtoint( Component.Text ) ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Volume' ) ;
            if( Component.Text <> '' ) then
            begin
                Volume := strtoint( Component.Text ) ;
            end ;
            Component := UUI.Get_Component_By_Name( 'Confirm' ) ;
            Confirm := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Contiguous' ) ;
            Contiguous := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Log' ) ;
            Log := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Overlay' ) ;
            Overlay := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Read_Check' ) ;
            Read_Check := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Replace' ) ;
            Replace := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Symlink' ) ;
            Symlink := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Truncate' ) ;
            Truncate := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Version' ) ;
            Versions := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Write_Check' ) ;
            Write_Check := Component.Text = 'true' ;
            Component := UUI.Get_Component_By_Name( 'Style' ) ;
            if( Component.Text = 'Expanded' ) then
            begin
                Style := Style_Expanded ;
            end else
            if( Component.Text = 'Condensed' ) then
            begin
                Style := Style_Condensed ;
            end ;
            
            Owner := 0 ;
            Component := UUI.Get_Component_By_Name( 'Owner' ) ;
            if( Component.UUI ) then
            begin
                S := Component.Text ;
                fillchar( Descriptors, sizeof( Descriptors ), 0 ) ;
                Descriptors[ 0 ].Item_Code := UAI_UIC ;
                Descriptors[ 0 ].Buffer_Length := sizeof( Owner ) ;
                Descriptors[ 0 ].Buffer_Address := int64( @Owner ) ;
                Descriptors[ 0 ].Return_Length_Address := int64( @Len ) ;
                Descriptors[ 0 ].MBO := 1 ;
                Descriptors[ 0 ].MBMO := $FFFFFFFF ;
                Len := 0 ;
                if( GETUAI( 0, S, int64( @Descriptors ) ) <> 0 ) then
                begin
                    if( not trystrtoint64( S, Owner ) ) then
                    begin
                        Result := COPY_UNKUSE ;
                        exit ;
                   end ;
                end ;
            end ;

Next we get the various other options. We set the boolean variables accordingly once so we don't have the overhead of getting each option from the UUI each time we need them. For the owner, we first try to get the UIC for the specified owner. If this fails, we use the specified UIC value. Of course, if this isn't an integer, it is an error. Note that we don't validate the UIC.

            Component := UUI.Get_Component_By_Name( 'Protection' ) ;
            Use_Protection := Component.UUI ;
            if( Use_Protection ) then
            begin
                S := Component.Text ;
                Protection := Parse_Protection( S ) ;
                if( Protection = -3 ) then
                begin
                    Result := COPY_INVQUAVAL ;
                    exit ;
                end ;
                if( Protection = -2 ) then
                begin
                    Result := COPY_INVQUAVAL ;
                    exit ;
                end ;
                if( Protection < 0 ) then
                begin
                    Result := COPY_INVQUAVAL ;
                    exit ;
                end ;
            end ;

Finally, we get the file protection options. We use the Parse_Protection function to convert the specification to the bit flags that represent it. If the result indicates a problem, we exit with the appropriate error.

In the next article, we will look at the code that actually performs the requested operation.