CREATE

In this article we will look at the CREATE CUSP. This is, perhaps, one of the simplest of the CUSPS. It creates a new file. First the documentation, and then the code.

CREATE
Creates one or more disk files.

Format

CREATE filespec{,...}

Arguments

filespec
The file specification for a file to create. There is no default for an omitted name or extension. If the specified file already exists, a new version is created. Multiple files can be specified.

Description

The CREATE command creates a new disk file. In interactive mode, each separate line that is entered after the command becomes a line in the new file. To terminate the file input, enter a control-Z.

When the CREATE command occurs in a command file, UCL reads input lines from the command file until a dollar sign ($) is encountered in the first position of a line, or Control-Z is encountered, or the end of the command file is encountered.

If multiple output files are specified, after the input is terminated for a file, the next file is created and following lines are written to that file until ended as above.
If the file specification includes a logical name list, the file is created in the first location in the list.

The new file will have the current user as the owner, unless the user has extended privileges, in which case the file's owner will be the owner of the parent directory or of the previous version of the file. Extended privileges include: SYSPRV, BYPASS, or user has a System User UIC.

Qualifiers

/{NO}LOG
Displays the file specification as each file is created.

/OWNER=owner
Assigns the specified user as owner of the file. The owner may be a user name or a UIC. SYSPRV is required to specify another user.

/PROTECTION(ownership[:access][,...])
Specified protection for the file. "ownership" is one of the following:

Value Meaning

S System

O Owner

G Group

W World

"access" is one or more of the following:

Value Meaning

R Read

W Write

E Execute

D Delete

If a value is not specified for each access category (or if /PROTECTION is not used), the protection is assigned from the existing file, or the default protection if there was no existing file.

Example

$ CREATE FILE1.TXT
Line one
Line two
.
.
.
Ctrl/Z
$
FILE1.TXT is created and lines are added to it until control-Z is pressed.

const UI =  'object Main:rectangle' + CR +
            '  top = 2' + 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 = "_Name:"' + CR +
            '  end' + CR +
            '' +
            '  object Options:rectangle' + CR +
            '    object label3:label' + CR +
            '      text = "User:"' + CR +
            '    end' + CR +
            '    object Owner:string' + CR +
            '      text = ""' + CR +
            '      hint = "User name/UIC"' + CR +
            '      left = label3.left + label3.width' + 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 Log:boolean' + CR +
            '      text = "false"' + CR +
            '      falsehint = "Click to display create operations"' + CR +
            '      truehint = "Click to disable display of create operations"' + CR +
            '    end' + CR +
            'end' ;

This is the UI specification for the CREATE CUSP.

function Run : int64 ;

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

begin
    Result := 0 ;
    OS := new( POS_UOS, Init ) ;
    C := Get_Symbol( 'create$defaults' ) ;
    E := _Create( 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 similar to the Run method of other CUSPs, so we won't belabor it here.

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

var C, S : string ;
    Component : TUUI_Component ;
    DefDir, DefDev : string ;
    P : integer ;
    Priv : int64 ;
    FileOwner : cardinal ;
    DefProt, FileProt : int64 ;
    Protection_Mask : integer ;
    I : integer ;
    Interactive : boolean ;
    Log : boolean ;
    Node, Access, Secondary_Node, Device, Path, Name, Extension, Version : string ;
    OS : POS_UOS ;
    Outf : string ; // Name of output file(s)
    OutFile : TCOM_UOS_File ;
    Privileges : boolean ;
    Protection : int64 ;
    SL : TStringList ;
    UIC, Owner : Cardinal ;
    Use_Protection : boolean ;
    UUI : TUUI ;

begin
    // Setup...
    Result := 0 ;
    UUI := TUUI.Create ;
    UUI.Definition := UI ;
    DefDir := GETDDIR ;
    DefDev := Get_Symbol( 'sys$disk:' ) ;
    Priv := Our_Current_Privilege ;
    Protection_Mask := $FFFF ; // Assume nothing specified by user
    DefProt := Get_Default_File_Protection( 0 ) ;
    UIC := Our_UIC ;
    Interactive := Interactive_Input ; // sys%input is a terminal
    Privileges := ( Priv and ( SYSPRV or BYPASS ) ) <> 0 ; // Have privileges
    if( not Privileges ) then
    begin
        if( UIC < 8 ) then // System UIC
        begin
            Privileges := True ;
        end ;
    end ;
    OS := new( POS_UOS, Init ) ;

The main code for CREATE sets up some variables that we will use below. The Privileges boolean indicates if the user has either SYSPRV or BYPASS.

// 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 ) ;

    // Processing...
    if( UUI.Execute( UI, Standalone ) ) then
    begin

Next we get the command line with defaults, and then execute the UI.

        // Parse and build output file list...
        Component := UUI.Get_Component_By_Name( 'Output' ) ;
        Outf := trim( Component.Text ) ;
        if( Outf = '' ) then
        begin
            Outf := UUI.Get_Parameter( 'Create', 'Output file' )
        end ;
        if( Outf = '' ) then
        begin
            Result := CUSP_OUTREQ ;
            exit ;
        end ;
        SL := TStringList.Create ;
        while( Outf <> '' ) do
        begin
            S := Parse_Parameter( ',', Outf ) ;
            PasStarlet.Parse_Filename( S, Node, Access, Secondary_Node, Device, Path,
                Name, Extension, Version ) ;
            if( ( Name = '' ) and ( Extension = '' ) ) then // No name or type specified
            begin
                Result := CUSP_OUTREQ ;
                SL.Free ;
                exit ;
            end ;
            if( Device = '' ) then
            begin
                Device := DefDev ;
            end ;
            if( Path = '' ) then
            begin
                Path := DefDir ;
            end ;
            S := Node + Access + Device + Path + Name + Extension + Version ;
            if( ( pos( '?', S ) + pos( '*', S ) ) > 0 ) then
            begin
                Result := CUSP_IVWILD ;
                SL.Free ;
                exit ;
            end ;
            SL.Add( S ) ;
        end ; // while( Output <> '' )

The output can be a single file or a comma-delimited list of files. So we must parse the output specification, defaulting the device and path, and adding each output file to the SL list. Wildcards are not valid in the output, so we exit with an error if such is encountered.

        Component := UUI.Get_Component_By_Name( 'Log' ) ;
        Log := Component.Text = 'true' ;
        Component := UUI.Get_Component_By_Name( 'Protection' ) ;
        Use_Protection := Component.UUI ;
        if( Use_Protection ) then
        begin
            S := Component.Text ;
            Protection := Parse_Protection( S, Protection_Mask ) ;
            if( Protection = -3 ) then
            begin
                Result := CUSP_CONFLICT ;
                exit ;
            end ;
            if( Protection = -2 ) then
            begin
                Result := CUSP_CONFLICT ;
                exit ;
            end ;
            if( Protection < 0 ) then
            begin
                Result := CUSP_CONFLICT ;
                exit ;
            end ;
        end ;
        Owner := 0 ;
        Component := UUI.Get_Component_By_Name( 'Owner' ) ;
        if( Component.UUI ) then
        begin
            Owner := Get_UIC_By_Name( Component.Text ) ;
            if( Owner = 0 ) then
            begin
                Result := CUSP_UNKUSE ;
                SL.Free ;
                exit ;
            end ;
            if( UIC <> Owner ) then // Setting owner different than us
            begin
                if( ( Priv and SYSPRV ) = 0 ) then // Do not have SYSPRV
                begin
                    Result := SS_NOPRIV ;
                    SL.Free ;
                    exit ;
                end ;
            end ;
        end ;

Next we get the log, protection, and owner qualifier values. A different owner is not allowed unless the user has SYSPRV. We exit if there are any errors.

        for I := 0 to SL.Count - 1 do
        begin
            S := SL[ I ] ;

            // Get file protection and owner, or directory owner if no file...
            FileProt := DefProt ;
            if( File_Exists( S ) ) then
            begin
                OutFile := Open_Binary_File( S, FAB_V_UFO ) ;
                if( Owner = 0 ) then // No owner specified
                begin
                    if( Privileges ) then
                    begin
                        FileOwner := Outfile.Owner ;
                    end else
                    begin
                        FileOwner := UIC ;
                    end ;
                end else
                begin
                    FileOwner := Owner ;
                end ;
                FileProt := OutFile.Protection ;
                OutFile.Free ;
            end else
            begin
                OutFile := Open_Binary_File( Path_For( S ), FAB_V_UFO ) ;
                if( Owner = 0 ) then // No owner specified
                begin
                    if( Privileges ) then
                    begin
                        FileOwner := Outfile.Owner ;
                    end else
                    begin
                        FileOwner := UIC ;
                    end ;
                end else
                begin
                    FileOwner := Owner ;
                end ;
                OutFile.Free ;
            end ;

Now we iterate through the output files. If the file already exists, we get the file's current owner and protection. If it doesn't, we get the owner of the parent directory. If we have privileges, and no owner qualifier was used, we use the file/directory owner, otherwise, we will use our own UIC as the owner.

            // Create file...
            OutFile := Open_Binary_File( S, FAB_V_CIF or FAB_V_SUP or FAB_V_UFO ) ;
            if( OutFile = nil ) then
            begin
                Result := LIB_Get_Exception( 0 ) ;
                exit ;
            end ;
            Outfile.Owner := FileOwner ;
            if( Use_Protection ) then
            begin
                OutFile.Protection := Protection or ( FileProt and Protection_Mask ) ;
            end ;

            // Get file contents from input...
            while( True ) do
            begin
                S := Get_Input( '' ) ;
                if( S = Control_Z ) then
                begin
                    break ;
                end ;
                if( not Interactive_Input ) then
                begin
                    if( copy( S, 1, 1 ) = '$' ) then
                    begin
                        break ;
                    end ;
                end ;
                S := Replace( S, CR, '', 0 ) ;
                OutFile.Writeln( PChar( S ) ) ;
                if( Outfile.IO_Error <> nil ) then
                begin
                    Result := Outfile.IO_Error.Get_Error ;
                    exit ;
                end ;
            end ;

            // Finish this file...
            OutFile.Free ;

            if( Log ) then
            begin
                OS^.OutputLn( RH_SysOutput, '%CREATE-I-CREATED, ' + S + ' created' ) ;
            end ;
        end ; // for I := 0 to SL.Count - 1
    end ; // if( UUI.Execute )
end ; // _Create

Next, we create the output file, setting the owner and/or protection code. Then we get the input to put into the file. A control-Z will exit the process. If we are not interactive (input is not from a terminal), then if the line begins with a dollar sign ($), the input is terminated. If there is a write error, we exit.

When done with the input, we close the file, and then write a log of the creation if requested by the user. Then we loop back for the next file, if one.

Finally, we've added a few routines to the CUSPLib module to support CREATE and other CUSPS.

function Our_UIC : cardinal ;

var s : string ;

begin
    S := GetJPI( 0, JPI_UIC ) ;
    Result := 0 ;
    move( PChar( S )[ 0 ], Result, sizeof( Result ) ) ;
end ;


function Our_Current_Privilege : int64 ;

var S : string ;

begin
    S := GetJPI( 0, JPI_CURPRIV ) ;
    move( PChar( S )[ 0 ], Result, sizeof( Result ) ) ;
end ;


function Path_For( S : string ) : string ;

var I : integer ;

begin
    I := length( S ) ;
    while( ( I > 0 ) and ( S[ I ] <> '\' ) ) do
    begin
        dec( I ) ;
    end ;
    Result := copy( S, 1, I ) ;
    if( Result = '' ) then
    begin
        Result := '\' ;
    end ;
end ;


var Descriptor : array[ 0..1 ] of TDVI_Descriptor ;
    SYS_Descriptor : array[ 0..3 ] of TSYS_Descriptor ;
    Buff, BufLen, Buff1, BufLen1 : int64 ;
    Buf : array[ 0..1023 ] of byte ;

function Interactive_Input : boolean ;

var IOSB : TIOSB ;

begin
    Buff := 0 ;
    BufLen := 0 ;
    fillchar( Descriptor, sizeof( Descriptor ), 0 ) ;
    Descriptor[ 0 ].Buffer_Length := sizeof( Buff ) ;
    Descriptor[ 0 ].Item_Code := DVI_DEVCHAR ; // DVIDEF item
    Descriptor[ 0 ].Buffer_Address := integer( @Buff ) ;
    Descriptor[ 0 ].Return_Length_Address := integer( @BufLen ) ;
    GETDVIW( 0, RH_SysInput, '', integer( @Descriptor ), integer( @IOSB ),
        0, 0, '', 1 ) ;
    Result := ( ( Buff and DEV_V_TRM ) <> 0 ) ; // Terminal device
end ;


var Descriptors : array[ 0..1 ] of TSYS_Descriptor ;
    Len : int64 ;

function Get_UIC_By_Name( S : string ) : cardinal ;

var I : integer ;

begin
    fillchar( Descriptors, sizeof( Descriptors ), 0 ) ;
    Descriptors[ 0 ].Item_Code := UAI_UIC ;
    Descriptors[ 0 ].Buffer_Length := sizeof( Result ) ;
    Descriptors[ 0 ].Buffer_Address := int64( @Result ) ;
    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 // Name lookup failed
    begin
        if( not trystrtoint( S, I ) ) then // Try S as UIC value
        begin
            Result := 0 ;
            exit ;
        end ;
        Result := I ;
    end ;
end ;

Our_UIC gets the current user's UIC. Out_Current_Privilege gets the current process privilege. Path_For extracts the device and path from a file specification. Interactive_User returns true if SYS$INPUT is from a terminal. Get_UIC_By_Name converts a user name to a UIC.

In the next article, we will cover CREATE/DIRECTORY.