FUNCTIONUnder review

FRead

FRead( nHandle, @cBufferVar, nQtdBytes ) --> nRet

Reads bytes into a buffer and returns the count.

FReadAdvPL

01 · OVERVIEW

Overview

FRead returns a number; data arrives in a preallocated buffer passed by reference. Do not replace that buffer with the returned count. Both old official and community examples contain sections not fully respecting this preparation: the adaptation uses Space(64), @cBuffer and a separate nRead. A short read can indicate EOF or error; capture FError before closing. The fragment prints no file content and assumes no guaranteed 64 bytes. (TOTVS, n.d., ref. 1)

02 · SYNTAX

Syntax

FRead( nHandle, @cBufferVar, nQtdBytes ) --> nRet

Parameters

nHandle

NumericRequired

Valid handle from FOpen/FCreate; zero is valid too.

cBufferVar

CharacterRequired

Buffer sized >= nQtdBytes, by reference.

nQtdBytes

NumericRequired

Maximum requested in this read.

Return value

Number of bytes actually read.

03 · PRACTICAL EXAMPLE

Commented example

#Include "Protheus.ch"
#Include "Fileio.ch"

User Function Ed393()
    Local nHandle := -1
    Local nError := 0
    Local cBuffer := Space(64)
    Local nRead
    // Pre-existing fictional file in the test context; shared reading.
    nHandle := FOpen("editorial-test.txt", FO_READ + FO_SHARED)
    If nHandle < 0
        nError := FError()
        ConOut(cValToChar(nError))
    Else
        // Buffer and requested size differ from the numeric return.
        nRead := FRead(nHandle, @cBuffer, 64)
        nError := FError()
        ConOut(cValToChar(nRead))
        If nError <> 0
            ConOut(cValToChar(nError))
        EndIf
        If !FClose(nHandle)
            ConOut(cValToChar(FError()))
        EndIf
    EndIf
Return Nil

Expected result

Count up to 64 bytes or a diagnostic; this is one read rather than a complete reader. Under review: editorial example neither compiled nor run in Protheus. Check includes, release, RDD and context before testing.

BEST PRACTICES

Check path, permissions, platform and handle ownership. Close only handles obtained by this routine, including complete-application error handling.
Under review: editorial example neither compiled nor run in Protheus. Check includes, release, RDD and context before testing.