Version: 2025

SalFileHandle

Namespace: PPJ.Runtime

Assembly: PPJ.Web.50 (5.0.0.0)

Provides SAL file and stream operations through a handle to a shared open-file object.

C#
VB.NET

public struct SalFileHandle : ValueType, ISerializable, IXmlSerializable

Public Structure SalFileHandle
    Implements ValueType, ISerializable, IXmlSerializable

Copies of this structure refer to the same underlying file. Closing one copy closes the shared stream. Error codes are stored in the structure on which the failing operation was invoked.

Example:

using PPJ.Runtime;

SalFileHandle file = SalFileHandle.Null;
if (file.Open("input.txt", Sys.OF_Read))
{
    try
    {
        SalString line = SalString.Empty;
        while (file.GetString(ref line, 1024))
            System.Console.WriteLine(line.ToString());
    }
    finally
    {
        file.Close();
    }
}

Properties

Handle

IntPtr: Gets the runtime identifier for the associated open file.

IsBinary

Boolean: Gets whether the associated file uses binary I/O.

IsNull

Boolean: Gets whether this handle has no associated open file.

LastError

Int32: Gets the error code saved by the most recent caught instance-operation exception.

Successful operations do not clear a previously recorded error.

Stream

Stream: Gets the underlying stream.

The stream is shared by copies of this handle. Closing it directly affects all users.

Methods

Close()

Closes the shared stream and clears this handle's file reference.

Returns: Boolean. True when an open stream was closed; false for a null handle or a caught I/O error.

Copies of the handle refer to the same stream and are also no longer usable after a successful close.

Copy(sSourcePath, sDestPath, bOverWrite)

Copies a file and reports a SAL file-copy status.

Parameter	Type	Description
sSourcePath	SalString	The source file path.
sDestPath	SalString	The destination file path.
bOverWrite	SalBoolean	True to permit replacing an existing destination file.

Returns: SalNumber. FILE_CopyOK on success; otherwise FILE_CopySrc, FILE_CopyExist, FILE_CopyDest, or FILE_CopyWrite according to the path state after the failure.

CreateDirectory(sDir)

Creates a directory and any missing parent directories.

Parameter	Type	Description
sDir	SalString	The directory path to create.

Returns: SalBoolean. True if the directory exists after creation; false for a caught exception.

FromHandle(handle)

Resolves a file handle previously obtained from a SAL file.

Parameter	Type	Description
handle	IntPtr	A valid live SAL file handle, or zero.

Returns: SalFileHandle. The resolved file handle, or Null for zero.

The identifier is a managed runtime handle, not an operating-system file handle.

GetChar()

Reads one character in text mode or one byte in binary mode.

Returns: SalNumber. The character or byte value, or -1 for end of stream, a null handle, or a read failure.

GetChar(nChar)

Reads the next character or byte into a caller-supplied variable.

Parameter	Type	Description
nChar	SalNumber	Receives the character code or byte value on success; unchanged on failure.

Returns: Boolean. True when a value was read; false for end of stream, a null handle, or a read failure.

GetCurrentDirectory(sPath)

Retrieves the process current working directory.

Parameter	Type	Description
sPath	SalString	Receives the current directory on success; unchanged on failure.

Returns: SalBoolean. True on success; false for a caught exception.

GetDateTime(sFilename, dtDateTime)

Reads a file's last-write time in local time.

Parameter	Type	Description
sFilename	SalString	The file path.
dtDateTime	SalDateTime	Receives the last-write time on success; unchanged on failure.

Returns: SalBoolean. True on success; false if the file is absent or an exception is caught.

GetDrive()

Returns the drive-letter prefix inferred from the current directory.

Returns: SalString. An uppercase letter followed by a colon, or "@:" when a drive letter cannot be determined.

GetObjectData(info, context)

Stores the current handle identifier for serialization.

Parameter	Type	Description
info	SerializationInfo	The serialization data receiving the Handle entry.
context	StreamingContext	The serialization context. Not used by this implementation.

Serializes the runtime handle only, not the file contents or a portable file-open description.

GetString(maxLength)

Reads a line of text with a SAL-style buffer limit.

Parameter	Type	Description
maxLength	Int32	The buffer size, including one position reserved for a terminator.

Returns: SalString. The line without its line ending; a SAL null value at end of stream; or an empty string if reading could not be started.

GetString(line, maxLength)

Reads a line and assigns it to the supplied variable.

Parameter	Type	Description
line	SalString	Receives the line without its line ending, or SAL null at end of stream. Unchanged if the handle is null or an exception occurs before assignment.
maxLength	Int32	The buffer size, including one position reserved for a terminator. At most maxLength minus one characters are read.

Returns: Boolean. True when a non-null line was returned; false for end of stream, a null handle, or a read failure.

Example:

using System.IO;
using System.Text;
using PPJ.Runtime;

using (MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes("Ada\n\nGrace\n")))
{
    SalFileHandle file = SalFileHandle.Null;
    file.Use(stream, Sys.OF_Read, Encoding.UTF8);
    try
    {
        SalString line = SalString.Empty;
        while (file.GetString(ref line, 81)) // Up to 80 characters plus a terminator slot.
        {
            // Processes "Ada", an empty line, and "Grace"; an empty line is not EOF.
            System.Console.WriteLine(line.ToString());
        }
    }
    finally
    {
        file.Close();
    }
}

Open(fileName, flags)

Performs the requested SAL file-open or path operation.

Parameter	Type	Description
fileName	String	The path to open, create, delete, or inspect.
flags	Int32	The bitwise combination of SAL OF_* access, mode, and sharing flags.

Returns: Boolean. True when the requested operation succeeds; false for an empty path, an unavailable path, or a caught exception.

Selects Unicode, UTF-7, or UTF-8 from the encoding flags, falling back to Encoding.Default. Delete, parse, and existence flags perform their operation without assigning a new stream. Reopen is unsupported and returns false after logging the error. Close any previous open stream before opening another.

Open(fileName, flags, encoding)

Performs the requested SAL file-open or path operation.

Parameter	Type	Description
fileName	String	The path to open, create, delete, or inspect.
flags	Int32	The bitwise combination of SAL OF_* access, mode, and sharing flags.
encoding	Encoding	The text encoding to use; recognized byte-order marks can override it when reading text.

Returns: Boolean. True when the requested operation succeeds; false for an empty path, an unavailable path, or a caught exception.

Delete, parse, and existence flags perform their operation without assigning a new stream. Reopen is unsupported and returns false after logging the error. Close any previous open stream before opening another.

PutChar(c)

Writes a character or byte to the stream.

Parameter	Type	Description
c	Int32	The value to write, converted to a character in text mode or a byte in binary mode.

Returns: Boolean. True when the value is written; false for a null handle, missing writer, or caught exception.

Writes the selected encoding preamble first if the stream position is zero.

PutString(text)

Writes text followed by a carriage return and line feed.

Parameter	Type	Description
text	String	The text to write. Null is rejected.

Returns: Boolean. True if writing succeeds; false for a null handle, null text, or a caught write failure.

Writes the selected encoding preamble first if the stream position is zero.

Read(maxLength)

Reads a block using the file's binary or text mode.

Parameter	Type	Description
maxLength	Int32	The maximum bytes in binary mode or characters in text mode.

Returns: SalString. The data read, or an empty string when nothing is read. Binary reads produce a blob.

Read(buffer, maxLength)

Reads a block from the current stream position.

Parameter	Type	Description
buffer	SalString	Receives the data read; initialized to the corresponding Empty value before reading.
maxLength	Int32	The maximum bytes in binary mode or characters in text mode.

Returns: SalNumber. The byte or character count, or zero when nothing was read or reading failed.

Returns a blob in binary mode and text in text mode.

Example:

using System.IO;
using PPJ.Runtime;

using (MemoryStream stream = new MemoryStream(new byte[] { 65, 0, 66 }))
{
    SalFileHandle file = SalFileHandle.Null;
    file.Use(stream, Sys.OF_Read | Sys.OF_Binary);
    try
    {
        SalString buffer = SalString.Empty;
        SalNumber count = file.Read(ref buffer, 16); // 3 bytes, although 16 were requested.
        byte[] bytes = buffer.GetBlob();            // { 65, 0, 66 }
        string text = buffer.ToString();            // "A": text ends at the zero byte.
        // Without OF_Binary, maxLength and the returned count measure characters.
    }
    finally
    {
        file.Close();
    }
}

Read(buffer, maxLength)

Reads a block from the current stream position.

Parameter	Type	Description
buffer	SalBinary	Receives the data read; initialized to the corresponding Empty value before reading.
maxLength	Int32	The maximum number of bytes to read.

Returns: SalNumber. The byte count, or zero when nothing was read or reading failed.

Reads bytes regardless of the file mode.

RemoveDirectory(sDir)

Deletes an empty directory.

Parameter	Type	Description
sDir	SalString	The directory to delete.

Returns: SalBoolean. True on success; false for a caught exception, including a nonempty directory.

The deletion is not recursive.

Seek(bytes, position)

Moves the stream position relative to a SAL seek origin.

Parameter	Type	Description
bytes	Int32	The signed byte offset from the origin.
position	Int32	FILE_SeekBegin, FILE_SeekCurrent, or FILE_SeekEnd.

Returns: Boolean. True if the seek succeeds; false for an invalid origin, null handle, or caught exception.

SetCurrentDirectory(sPath)

Changes the process current working directory.

Parameter	Type	Description
sPath	SalString	The directory to make current.

Returns: SalBoolean. True on success; false for a caught exception.

SetDateTime(sFilename, dtDateTime)

Sets a file's last-write time using local time.

Parameter	Type	Description
sFilename	SalString	The file path.
dtDateTime	SalDateTime	The new last-write time.

Returns: SalBoolean. True on success; false if the file is absent or an exception is caught.

SetDrive(sDriveLetter)

Changes the process current directory to the requested drive root.

Parameter	Type	Description
sDriveLetter	SalString	A value whose first character specifies the drive.

Returns: SalBoolean. True if already on the requested drive or if the directory is changed; false for an empty value or caught exception.

Tell()

Returns the current byte position in the stream.

Returns: SalNumber. The byte offset from the start, or -1 for a null handle or caught exception.

Use(stream, flags)

Associates this handle with an existing stream.

Parameter	Type	Description
stream	Stream	The existing stream to use. Closing this file handle also closes the stream.
flags	Int32	The bitwise combination of SAL OF_* access, mode, and sharing flags.

Returns: Boolean. True after the stream wrapper is created. Construction exceptions propagate.

Selects Unicode, UTF-7, or UTF-8 from the encoding flags, falling back to Encoding.Default. Access flags configure the reader and writer; they do not recreate or truncate the existing stream. Close a previous association before replacing it.

Example:

using System.IO;
using System.Text;
using PPJ.Runtime;

using (MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes("Ada")))
{
    SalFileHandle file = SalFileHandle.Null;
    file.Use(stream, Sys.OF_Read | Sys.OF_UTF8);
    try
    {
        SalString text = file.Read(3); // "Ada"
    }
    finally
    {
        file.Close(); // Also closes stream; it cannot be reused afterward.
    }
}

Use(stream, flags, encoding)

Associates this handle with an existing stream.

Parameter	Type	Description
stream	Stream	The existing stream to use. Closing this file handle also closes the stream.
flags	Int32	The bitwise combination of SAL OF_* access, mode, and sharing flags.
encoding	Encoding	The text encoding to use; recognized byte-order marks can override it when reading text.

Returns: Boolean. True after the stream wrapper is created. Construction exceptions propagate.

Access flags configure the reader and writer; they do not recreate or truncate the existing stream. Close a previous association before replacing it.

Example:

using System.IO;
using System.Text;
using PPJ.Runtime;

using (MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes("Ada")))
{
    SalFileHandle file = SalFileHandle.Null;
    file.Use(stream, Sys.OF_Read, Encoding.UTF8);
    try
    {
        SalString text = file.Read(3); // "Ada"
    }
    finally
    {
        file.Close(); // Closing the handle also closes the supplied stream.
    }
}

Write(str, length)

Writes a prefix of the supplied buffer at the current stream position.

Parameter	Type	Description
str	SalString	The value to write. Must not be a null object reference.
length	Int32	The maximum number of buffer elements to write, limited to the available data.

Returns: SalNumber. The number of elements written, or zero if no data is written or a caught error occurs.

In binary mode writes the low bytes of the full string buffer; in text mode writes characters using the selected encoding and emits a preamble at position zero.

Write(binary, length)

Writes a prefix of the supplied buffer at the current stream position.

Parameter	Type	Description
binary	SalBinary	The value to write. Must not be a null object reference.
length	Int32	The maximum number of buffer elements to write, limited to the available data.

Returns: SalNumber. The number of elements written, or zero if no data is written or a caught error occurs.

Writes raw bytes regardless of the file mode.

Used By

Name	Description
Sal.FileGetChar
Sal.FileGetStr
Sal.FilePutChar
Sal.FilePutStr
Sal.FileRead
Sal.FileSeek
Sal.FileTell
Sal.FileWrite
Sal.WindowHandleToNumber	Returns a runtime handle identifier as a SAL number.
SalFileHandle.FromHandle	Resolves a file handle previously obtained from a SAL file.
Vis.FileClose
Vis.FileRead
Vis.FileReadString
Vis.FileSeek
Vis.FileTell
Vis.FileWrite
Vis.FileWriteString
XSal.GZipPutChar

Properties​

Handle​

IsBinary​

IsNull​

LastError​

Stream​

Methods​

Close()​

Copy(sSourcePath, sDestPath, bOverWrite)​

CreateDirectory(sDir)​

FromHandle(handle)​

GetChar()​

GetChar(nChar)​

GetCurrentDirectory(sPath)​

GetDateTime(sFilename, dtDateTime)​

GetDrive()​

GetObjectData(info, context)​

GetString(maxLength)​

GetString(line, maxLength)​

Open(fileName, flags)​

Open(fileName, flags, encoding)​

PutChar(c)​

PutString(text)​

Read(maxLength)​

Read(buffer, maxLength)​

Read(buffer, maxLength)​

RemoveDirectory(sDir)​

Seek(bytes, position)​

SetCurrentDirectory(sPath)​

SetDateTime(sFilename, dtDateTime)​

SetDrive(sDriveLetter)​

Tell()​

Use(stream, flags)​

Use(stream, flags, encoding)​

Write(str, length)​

Write(binary, length)​

Used By​

Properties

Handle

IsBinary

IsNull

LastError

Stream

Methods

Close()

Copy(sSourcePath, sDestPath, bOverWrite)

CreateDirectory(sDir)

FromHandle(handle)

GetChar()

GetChar(nChar)

GetCurrentDirectory(sPath)

GetDateTime(sFilename, dtDateTime)

GetDrive()

GetObjectData(info, context)

GetString(maxLength)

GetString(line, maxLength)

Open(fileName, flags)

Open(fileName, flags, encoding)

PutChar(c)

PutString(text)

Read(maxLength)

Read(buffer, maxLength)

Read(buffer, maxLength)

RemoveDirectory(sDir)

Seek(bytes, position)

SetCurrentDirectory(sPath)

SetDateTime(sFilename, dtDateTime)

SetDrive(sDriveLetter)

Tell()

Use(stream, flags)

Use(stream, flags, encoding)

Write(str, length)

Write(binary, length)

Used By