xHarbour Reference Documentation > Function Reference

BlobDirectExport()

Exports the contents of a binary large object (BLOB) to a file.

Syntax

BlobDirectExport( <nBlobID>, <cTargetFile>, [<nMode>] ) --> lSuccess

Arguments

<nBlobID>

<nBlobID> is the numeric identifier of the binary large object to export. The ID can be obtained using functions BlobDirectPut() or DbFieldInfo( DBS_BLOB_POINTER, <nFieldPos> ). An array of blob IDs can also be obtained using BlobRootGet() when the blob IDs are previously written to the root area of a blob file.

<cTargetFile>

This is a character string containing the name of the file to receive the exported data. It must be specified with a file extension. If <cTargetFile> contains no drive and/or directory information, the current directory is used. SET DEFAULT and SET PATH settings are ignored.

<nMode>

A numeric value specifying how to write data to the target file. #define constants must be used for this parameter.

Constants for BlobDirectExport()

Constant	Description
BLOB_EXPORT_APPEND	Appends to the target file
BLOB_EXPORT_OVERWRITE *)	Overwrites the target file
*) default value

Return

The return value is .T. (true) if data is successfully exported, otherwise .F. (false) is returned.

Description

BlobDirectExport() copies the contents of a single binary large object (BLOB) to an external file. The object is identified by its numeric ID. A BLOB is stored either in a memo field (DBFCDX RDD) or in a stand alone DBV file which is not associated with a database file (DBFBLOB RDD). BlobDirectExport() is usually required for the latter case. If BLOBs are stored in a database with an associated memo file, function BlobExport() is more comfortable to use, since it accepts a numeric field position of a memo field, rather than a numeric BLOB identifier.

The numeric BLOB ID is obtained using DbFieldInfo() or must be taken from the array returned by BlobRootGet().

If the target file does not exist, it is created. If it exists, it is either overwritten or data is appended to the file, depending on <nMode>. When the file operation fails, BlobDirectExport() returns .F. (false) and function NetErr() is set to .T. (true). This can happen when the target file is currently locked by another process in concurrent file access.

Notes:  BLOBs are stored in memo files having the .FPT or .DBV extension. They are maintained by the RDDs DBFCDX or DBFBLOB. DBFNTX, in contrast, does not support BLOBs.

The file Blob.ch must be #included for BlobDirectExport() to work.

Info

See also:	BlobDirectGet(), BlobDirectImport(), BlobDirectPut(), BlobExport(), BlobRootGet(), DbFieldInfo()
Category:	Blob functions , Database functions
Header:	blob.ch
Source:	rdd\dbcmd.c, rdd\dbffpt\dbffpt1.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates two possibilities of exporting BLOB data.
// The first example uses the DBFCDX RDD while the second uses the
// DBFBLOB RDD which does not maintain a database file, but only the
// BLOB file.

   #include "Blob.ch"

   REQUEST DBFBLOB
   REQUEST DBFCDX

   PROCEDURE Main
      LOCAL nBlobID, nFieldPos
      LOCAL aBlobID

      // DBF and FPT file exist
      USE PhotoArchive ALIAS Photos VIA "DBFCDX"
      LOCATE FOR FIELD->PhotoName = "Sunset in Malibu"

      IF Found()
         nFieldPos := FieldPos( "JPEG" )
         nBlobID   := DbFieldInfo( DBS_BLOB_POINTER, nFieldPos )

         IF BlobDirectExport( nBlobID, "Sunset.jpg" )
            ? "File successfully eported"
         ELSE
            ? "Unable to export BLOB data"
         ENDIF
      ENDIF

      // Only DBV file exists
      USE BlobStorage ALIAS Blob VIA "DBFBLOB"
      aBlobID := BlobRootGet()

      IF Valtype( aBlobID ) == "A"
         // Export second BLOB to file
         IF BlobDirectExport( aBlobID[2], "Picture02.jpg" )
            ? "File successfully eported"
         ELSE
            ? "Unable to export BLOB data"
         ENDIF
      ELSE
         ? "Error: Blob root is not created"
      ENDIF

      USE
   RETURN