xHarbour Reference Documentation > Function Reference

BlobDirectImport()

Imports a file into a binary large object (BLOB).

Syntax

BlobDirectImport( <nOldBlobID>, <cSourceFile> ) --> nNewBlobID

Arguments

<nOldBlobID>

<nOldBlobID> is the numeric identifier of the binary large object to receive the file contents of <cSourceFile>. 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.

All data of <nOldBlobID> is discarded, and the BLOB receives a new ID which is returned by the function. If zero is passed, a new BLOB is added to the BLOB file.

<cSourceFile>

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

If <cSourceFile> does not exist, a runtime error is raised. If the file cannot be opened due to another process having exclusive access to the file, function NetErr() is set to .T. (true).

Return

The function returns a numeric value which is the BLOB identifier of the new BLOB. The return value is zero, when the operation fails.

Description

BlobDirectImport() copies the contents of an external file into a single binary large object (BLOB). 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). BlobDirectImport() is usually required for the latter case. If BLOBs are stored in a database with an associated memo file, function FieldPut() 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().

When data is imported into an existing BLOB, the BLOB is entirely discarded and a new BLOB is created. As a consequence, the existing BLOB ID <nOldBlobID> becomes invalid, and BlobDirectImport() returns a new BLOB ID. The imported data can only be accessed via the new BLOB ID.

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 BlobDirectImport() to work.

Info

See also:	BlobDirectGet(), BlobDirectExport(), BlobExport(), BlobGet(), BlobImport(), 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 how to import JPG files into a DBV file.

   #include "Blob.ch"

   REQUEST DBFBLOB

   PROCEDURE Main
      LOCAL aFile
      LOCAL aFiles  := Directory( "*.jpg" )
      LOCAL aBlobID := {}

      DbCreate( "ImageArchive", {}, "DBFBLOB" )

      USE ImageArchive NEW VIA "DBFBLOB"

      FOR EACH aFile IN aFiles
         AAdd( aBlobID, BlobDirectImport( 0, aFile[1] ) )
      NEXT

      IF BlobRootLock() .AND. BlobRootPut( aBlobID )
         BlobRootUnlock()
      ELSE
         Alert( "Unable to lock BLOB root;try again later" )
      ENDIF

      USE
   RETURN