File Management extended stored procedures

xp_GetTempDir

Retrieves the path of the directory designated for temporary files.

Syntax

exec [{result}=] master..xp_GetTempDir {value OUTPUT}

Arguments

value

[out] varchar variable, receives path to a Temp Windows directory. Must have an OUTPUT modifier.

result

[out] Optional int variable, receives return code

Return Code Values

Length of value in bytes (success) or -1 (failure)

xp_DirCreate

Creates a new directory, including the creation of parent directories as needed.

Syntax

exec [{result}=] master..xp_DirCreate {value}

Arguments

value

[in] varchar variable, path to a directory to be created

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

xp_DirExists

Tests if a specified directory exists.

Syntax

exec {result} = master..xp_DirExists {value}

Arguments

value

[in] varchar variable, path to a directory

result

[out] Required int variable, receives return code

Return Code Values

1 (directory exists), 0 (directory not exists), or -1 (failure)

xp_DirRemove

Deletes an existing empty directory.

Syntax

exec {result} = master..xp_DirRemove {value}

Arguments

value

[in] varchar variable, path to a directory to be deleted.

result

[out] Required int variable, receives return code.

Return Code Values

1 (directory was successfully deleted) or -1 (failure)

xp_FileOpen

Opens (or creates) file for reading or writing.

Syntax

exec {result} = master..xp_FileOpen {filename}[, {mode}]

Arguments

filename

[in] varchar variable, path to a file to be opened

mode

[in] int variable, defines file access mode, must be a combination (logical OR) of the following constants:

Value	Meaning
0xFFFF	If the file exists, open for write access, otherwise, create a new file
0x00	Open for read access only
0x01	Open for write access only
0x02	Open for read and write access
0x10	Read and write access is denied for others
0x20	Write access is denied for others
0x30	Read access is denied for others
0x40	Allows full access for others

Default value for mode is 0 (Open for read access only)

result

[out] Required int variable, receives file handle or an error code

Return Code Values

Zero or greater file handle (success) or -1 (failure)

Remarks

File handle value is used in subsequent calls to most of xp_FileXXXX procedures.

xp_FileClose

Closes file.

Syntax

exec [{result}=] master..xp_FileClose {handle}

Arguments

handle

[in] int variable, handle to the file to be closed

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

Remarks

File handle must be a value returned by xp_FileOpen.

xp_FileSeek

Repositions read/write point.

Syntax

exec [{result}=] master..xp_FileSeek {handle}, {offset}, {origin}

Arguments

handle

[in] int variable, handle to the file

offset

[in] int variable, number of bytes to move

origin

[in] int variable, starting position:

Value	Meaning
0	The file pointer is positioned offset bytes from the beginning of the file
1	The file pointer is positioned offset bytes from its current position
2	The file pointer is positioned offset bytes from the end of the file

result

[out] Optional int variable, receives return code

Return Code Values

Zero or greater current file pointer position (success) or -1 (failure).

Remarks

File handle must be a value returned by xp_FileOpen.

xp_FileWrite

Writes an arbitrary data block to a file, starting at the position indicated by the file pointer. After the write operation has been completed, the file pointer is adjusted by the number of bytes actually written.

Syntax

exec [{result}=] master..xp_FileWrite {handle}, {data}

Arguments

handle

[in] int variable, handle to the file

data

[in] char, varchar, nvarchar, binary, varbinary variable, a data to be written

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

Remarks

File handle must be a value returned by xp_FileOpen. File must be open for write.

xp_FileRead

Reads an arbitrary data block from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read.

Syntax

exec [{result}=] master..xp_FileRead {handle}, {data OUTPUT}, {count}

Arguments

handle

[in] int variable, handle to the file

data

[out] char, varchar, nvarchar, binary, varbinary variable, a buffer for data to be read into. Must have an OUTPUT modifier.

count

[in] int variable, specifies the number of bytes to be read from the file

result

[out] Optional int variable, receives return code

Return Code Values

Zero or greater count of read bytes (success) or -1 (failure)

Remarks

File handle must be a value returned by xp_FileOpen. File must be open for read.

xp_FileWriteLine

Writes line to end of a text file (e.g., where text is separated by linebreaks, ASCII codes 13 and 10)

Syntax

exec [{result}=] master..xp_FileWriteLine {handle}, {data}

Arguments

handle

[in] int variable, handle to the file

data

[in] char, varchar, binary, varbinary variable, a data to be written

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

Remarks

File handle must be a value returned by xp_FileOpen. File must be open for write.

xp_FileReadLine

Subsequently reads lines from a text file (e.g., where text is separated by linebreaks, ASCII codes 13 and 10)

Syntax

exec [{result}=] master..xp_FileReadLine {handle}, {data OUTPUT}, {count}

Arguments

handle

[in] int variable, handle to the file

data

[out] char, varchar, nvarchar, binary, varbinary variable, a buffer for data to be read into. Must have an OUTPUT modifier.

count

[in] int variable, specifies the number of bytes to be read from the file

result

[out] Optional int variable, receives return code

Return Code Values

Zero or greater count of read bytes (success) or -1 (failure)

Remarks

File handle must be a value returned by xp_FileOpen. File must be open for read.
Return code value 0 and data value NULL means there an empty line was read.
Return code value -1 and data value NULL means no more lines left (end of file).

xp_FileSize

Retrieves the size, in bytes, of a specified file.

Syntax

exec {result} = master..xp_FileSize {handle}

Arguments

handle

[in]
int variable, handle to the file
OR
varchar variable, filename

result

[out] Required int variable, receives file size in bytes

Return Code Values

Zero or greater file size in bytes (success) or -1 (failure)

Remarks

When handle is int then it must be a value returned by xp_FileOpen, else it must be a path to the file

xp_IniReadKey

Retrieves a string from the specified section in an initialization file.

Syntax

exec [{result}=] master..xp_IniWriteKey {filename}, {section}, {key}, {default} {value OUTPUT}

Arguments

filename

[in] varchar variable, name of the file

section

[in] varchar variable, name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string can be any combination of uppercase and lowercase letters

key

[in] varchar variable, name of the key which value will be read

default

[in] varchar variable, default value to be returned when the key or section can not be found or read

value

[out] varchar variable, receives the key value from the file. Must have an OUTPUT modifier.

result

[out] Optional int variable, receives return code

Return Code Values

Zero or greater length of returned value (success) or -1 (failure)

xp_IniWriteKey

Copies a string into the specified section of the specified initialization file.

Syntax

exec [{result}=] master..xp_IniWriteKey {filename}, {section}, {key}, {value}

Arguments

filename

[in] varchar variable, name of the file

section

[in] varchar variable, name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string can be any combination of uppercase and lowercase letters

key

[in] varchar variable, name of the key to be associated with a string. If the key does not exist in the specified section, it is created

value

[in] varchar variable, string to be written to the file

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

xp_IniDeleteKey

Deletes a key from the specified section in an initialization file. exec [{result}=] master..xp_IniDeleteKey {filename}, {section}, {key}

Arguments

filename

[in] varchar variable, name of the file

section

[in] varchar variable, name of the section from which the string will be deleted

key

[in] varchar variable, name of the key to be deleted from the section

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

xp_IniDeleteSection

Deletes entire section in an initialization file.

Syntax

exec [{result}=] master..xp_IniDeleteSection {filename}, {section}

Arguments

filename

[in] varchar variable, name of the file

section

[in] varchar variable, name of the section to be deleted

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)

xp_FormatStr

Returns a formatted string assembled from a format string and an array of arguments.

Syntax

exec [{result}=] master..xp_FormatStr {data OUTPUT}, {template}, [, argument1, [argument2, ... [argumentN]]]

Arguments

data

[out] varchar variable, receives the result string. Must have an OUTPUT modifier.

template

[in] varchar variable, is a format character string with placeholders for argument values, similar to that supported by the C-language sprintf function

argument1 ... argumentN

[in] Optional bit, int, float, money, varchar, nvarchar variables, values to be substituted into the template

result

[out] Optional int variable, receives return code

Return Code Values

1 (success) or -1 (failure)