4.4 BFILE APIs in Different Programmatic Interfaces

This section lists all the APIs from different Programmatic Interfaces supported by Oracle Database.

Note:

The PL/SQL DBMS_LOB package provides a rich set of operations on BFILEs. If you are using a different Programmatic Interface where some of these operations are not provided, then call the corresponding PL/SQL DBMS_LOB procedure or function.

See Also:

Comparing the LOB Interfaces

4.4.1 PL/SQL APIs for BFILEs

This section describes the PL/SQL APIs that you can use with BFILEs.

See Also:

DBMS_LOB

Table 4-3 DBMS_LOB functions and procedures for BFILEs

Category	Function/ Procedure	Description
Sanity Checking	FILEEXISTS	Checks if the BFILE exists on the server
	FILEGETNAME	Gets the DIRECTORY object name and file name
	BFILENAME	Sets the name of a BFILE in a locator without checking if the directory or file exists
Open/Close	OPEN, FILEOPEN	Opens a file. Use OPEN instead of FILEOPEN.
	ISOPEN, FILEISOPEN	Checks if the file was opened using the input BFILE locators. Use ISOPEN instead of FILEISOPEN.
	CLOSE, FILECLOSE	Closes the file. Use CLOSE instead of FILECLOSE.
	FILECLOSEALL	Closes all previously opened files.
Read Operations	GETLENGTH	Gets the length of the BFILE
	READ	Reads data from the BFILE starting at the specified offset.
	SUBSTR	Returns part of the BFILE value starting at the specified offset.
	INSTR	Returns the matching position of the nth occurrence of the pattern in the BFILE.
Operations involving multiple locators	:= (operator)	Assigns a BFILE locator to another
	LOADCLOBFROMFILE	Loads character data from a file into a LOB
	LOADBLOBFROMFILE	Loads binary data from a file into a LOB
	LOADFROMFILE	Loads BFILE data into a LOB (deprecated)
	COMPARE	Compares the value of two BFILEs.

Example 4-3 PL/SQL API for BFILEs

declare
  f           BFILE;
  f2          BFILE;
  b           BLOB;
  c           CLOB;
  dest_offset NUMBER;
  src_offset  NUMBER;
  lang        NUMBER;
  warn        NUMBER;
  buffer      RAW(128);
  amt         NUMBER;
  len         NUMBER;
  pos         NUMBER;
  filename    VARCHAR2(128);
  dirname     VARCHAR2(128);
BEGIN

   /* Select out a BFILE locator */
  SELECT ad_graphic INTO f FROM print_media WHERE product_id = 1 AND ad_id = 1;
 
  /*------------------------------------------------------------------*/
  /*---------------------- Sanity Checking ---------------------------*/
  /*------------------------------------------------------------------*/
 
  /*-------------- Determining Whether a BFILE Exists ----------------*/
  if DBMS_LOB.FILEEXISTS(f) = 1 then
    DBMS_OUTPUT.PUT_LINE('F exists!');
  else
    DBMS_OUTPUT.PUT_LINE('F does not exist :(');
    return;
  end if;
 
  /*------ Getting Directory Object Name and File Name of a BFILE ----*/
  DBMS_LOB.FILEGETNAME(f, dirname, filename);
  DBMS_OUTPUT.PUT_LINE('F: directory: '|| dirname ||' filename: '|| filename);
 
  /*------------------------------------------------------------------*/
  /*----------------------- Open/Close -------------------------------*/
  /*------------------------------------------------------------------*/
 
  /*----------------------- Opening a BFILE --------------------------*/
  DBMS_LOB.OPEN(f, DBMS_LOB.LOB_READONLY);
 
  /*-------------- Determining Whether a BFILE Is Open ---------------*/
  if DBMS_LOB.ISOPEN(f) = 1 then
    DBMS_OUTPUT.PUT_LINE('F is open!');
  else
    DBMS_OUTPUT.PUT_LINE('F is not open :(');
  end if;
 
  /*----------------------- Closing a BFILE --------------------------*/
  DBMS_LOB.CLOSE(f);
 
  /*------------ Closing All Open BFILEs with FILECLOSEALL -----------*/
  DBMS_LOB.FILECLOSEALL;
 
  /*------------------------------------------------------------------*/
  /*-------------------- BFILE operations ----------------------------*/
  /*------------------------------------------------------------------*/
 
  DBMS_LOB.OPEN(f, dbms_lob.lob_readonly);
 
  /*----------------- Getting the Length of a BFILE ------------------*/
  len := DBMS_LOB.GETLENGTH(f);
  DBMS_OUTPUT.PUT_LINE('dbms_lob.getlength: '||len);
 
  /*------------------------ Reading BFILE Data ----------------------*/
  amt := 15;
  DBMS_LOB.READ(f, amt, 1, buffer);
  DBMS_OUTPUT.PUT_LINE('dbms_lob.read: '||UTL_RAW.CAST_TO_VARCHAR2(buffer));
 
  /*--------- Reading a Portion of BFILE Data Using SUBSTR -----------*/
  buffer := DBMS_LOB.SUBSTR(f, 15, 3);
  DBMS_OUTPUT.PUT_LINE('dbms_lob.substr: '||UTL_RAW.CAST_TO_VARCHAR2(buffer));
 
  /*------ Checking If a Pattern Exists in a BFILE Using INSTR -------*/
  pos :=  DBMS_LOB.INSTR(f, utl_raw.cast_to_raw('BFILE'), 1, 1);
  if pos != 0 then
    DBMS_OUTPUT.PUT_LINE('dbms_lob.instr: "BFILE" word exists in position ' || pos);
  else
    DBMS_OUTPUT.PUT_LINE('dbms_lob.instr: "BFILE" word does not exist in file');
  end if;
 
  /*------------------------------------------------------------------*/
  /*------------- Operations involving 2 locators ---------------------*/
  /*------------------------------------------------------------------*/
 
  /*----------------- Assigning a BFILE Locator ----------------------*/
  f2 := f; -- where f2 is also a bfile variable
 
  amt := 15;
  DBMS_LOB.READ(f2, amt, 1, buffer);
  DBMS_OUTPUT.PUT_LINE('assign: dbms_lob.read: '||UTL_RAW.CAST_TO_VARCHAR2(buffer));
 
  /*--------------- Loading a LOB with BFILE Data --------------------*/
  /* Select out BLOB and CLOB for update so we can write to them */
  select ad_composite, ad_sourcetext into b, c
  from print_media where product_id = 1 and ad_id = 1 for update;
 
  /* Load BLOB from BFILE */
  dest_offset := 1;
  src_offset  := 1;
 
  DBMS_LOB.LOADBLOBFROMFILE(b, f, dbms_lob.lobmaxsize, dest_offset, src_offset);
 
  /* Load CLOB from BFILE, for this operation is necessary to know the charset
   * id of BFILE to read it correctly */
  dest_offset := 1;
  src_offset  := 1;
  lang        := 0;
  /* Specifying the amount as DBMS_LOB.LOBMAXSIZE to copy till end of file */
  DBMS_LOB.LOADCLOBFROMFILE(c, f, DBMS_LOB.LOBMAXSIZE, dest_offset, src_offset,
                            NLS_CHARSET_ID('utf8'), lang, warn);
 
  /*-------------- Comparing All or Parts of Two BFILES -------------*/
  SELECT ad_graphic INTO f2 FROM print_media WHERE product_id = 2 AND ad_id = 1;
  DBMS_LOB.OPEN(f2, dbms_lob.lob_readonly);
  if DBMS_LOB.COMPARE(f, f2, 10, 1, 1) = 0 then
    DBMS_OUTPUT.PUT_LINE('dbms_lob.compare: They are equals!!');
  else
    DBMS_OUTPUT.PUT_LINE('dbms_lob.compare: They are not equals :(');
  end if;
 
  -- Close just f
  DBMS_LOB.CLOSE(f);
 
  -- Close the rest of bfiles opended
  DBMS_LOB.FILECLOSEALL;
 
END;
/

4.4.2 JDBC API for BFILEs

This section describes the JDBC APIs that you can use to work with BFILEs.

In JDBC, the oracle.jdbc.OracleBfile interface provides methods for performing operations on BFILE data in the database. It encapsulates the BFILE locators, so you do not deal with locators, but instead use methods and properties provided to perform operations and get state information.

To retrieve the locator for the most current row, you must call the getBFILE() method on the OracleResultSet each time a move operation is made, depending on whether the instance is a BFILE.

See Also:

Working with LOBs and BFILEs

Table 4-4 JDBC APIs for BFILEs

Category	Function/ Procedure	Description
Sanity Checking	boolean fileExists()	Checks if the BFILE exists on the server
	public java.lang.String getName()	Gets the file name
	public java.lang.String getDirAlias()	Gets the DIRECTORY object name
Open/Close	public void openFile()	Opens a file.
	public boolean isFileOpen()	Checks if the file was opened using the input BFILE locators. .
	public void closeFile()	Closes the file. Use CLOSE instead of FILECLOSE.
Read Operations	long length()	Gets the length of the BFILE
	public java.io.InputStream getBinaryStream()	Reads the BFILE as a binary stream.
	byte[] getBytes(long, int)	Gets the contents of the BFILE as an array of bytes, given an offset
	int getBytes(long, int, byte[])	Reads a subset of the BFILE into a byte array
	long position(oracle.jdbc.OracleBfile, long)	Finds the first appearance of the given BFILE contents within the LOB, from the given offset.
	long position(byte[], long)	Finds the first appearance of the given byte array within the BFILE, from the given offset
Operations involving multiple locators	[use equal sign]	Assigns a BFILE locator to another

Example 4-4 JDBC API for BFILEs

static void run_query() throws Exception {
 
  try(
      OracleConnection con = getConnection();
      Statement       stmt = con.createStatement();
      ){
 
    ResultSet   rs       = null;
 
    OracleBfile f        = null;
    OracleBfile f2       = null;
    OracleBfile f3       = null;
 
    InputStream in       = null;
    String      output   = null;
    byte        buffer[] = new byte[15];
    long        pos;
 
    String      filename = null;
    String      dirname  = null;
    long        len      = 0;
 
    rs = stmt.executeQuery("select ad_graphic from print_media where product_id = 1");
    rs.next();
    f = (OracleBfile)((OracleResultSet)rs).getBfile(1);
    rs.close();
 
    rs = stmt.executeQuery("select ad_graphic from print_media where product_id = 2");
    rs.next();
    f2 = (OracleBfile)((OracleResultSet)rs).getBfile(1);
    rs.close();
 
    stmt.close();
 
    /*------------------------------------------------------------------*/
    /*---------------------- Sanity Checking ---------------------------*/
    /*------------------------------------------------------------------*/
 
    /*-------------- Determining Whether a BFILE Exists ----------------*/
    if (f.fileExists())
      System.out.println("F exists!");
    else
      System.out.println("F does not exist :(");
 
    /*------ Getting Directory Object Name and File Name of a BFILE ----*/
    dirname  = f.getDirAlias();
    filename = f.getName();
 
    System.out.println("Directory: " + dirname + " Filename: " + filename);
 
    /*------------------------------------------------------------------*/
    /*----------------------- Open/Close -------------------------------*/
    /*------------------------------------------------------------------*/
 
    /*----------------------- Opening a BFILE --------------------------*/
    f.open(LargeObjectAccessMode.MODE_READONLY);
 
    /*-------------- Determining Whether a BFILE Is Open ---------------*/
    if (f.isOpen())
      System.out.println("F is open!");
    else
      System.out.println("F is not open :(");
 
    /*----------------------- Closing a BFILE --------------------------*/
    f.close();
 
    /*------------------------------------------------------------------*/
    /*-------------------- BFILE operations ----------------------------*/
    /*------------------------------------------------------------------*/
 
    f.open(LargeObjectAccessMode.MODE_READONLY);
 
    /*----------------- Getting the Length of a BFILE ------------------*/
    len = f.length();
    System.out.println("F Length: "+len);
 
    /*------------------------ Reading BFILE Data ----------------------*/
    in = f.getBinaryStream();
    in.read(buffer);
    in.close();
 
    output = new String(buffer);
    System.out.println("Buffer: " + output);
 
    /*---- Checking If a Pattern Exists in a BFILE Using POSITION ------*/
    pos = f.position("BFILE".getBytes(), 1);
 
    if (pos != -1)
      System.out.println("\"BFILE\" word exists in position: " + pos);
    else
      System.out.println("\"BFILE\" word doesn't exist :( " );
 
    /*------------------------------------------------------------------*/
    /*------------- Operations involing 2 locators ---------------------*/
    /*------------------------------------------------------------------*/
 
    /*----------------- Assigning a BFILE Locator ----------------------*/
    f3 = f;
 
    in = f3.getBinaryStream();
    in.read(buffer);
    in.close();
 
    output = new String(buffer);
    System.out.println("assign: Buffer: " + output);
 
    /*-------------- Comparing All or Parts of Two BFILES -------------*/
    f2.open(LargeObjectAccessMode.MODE_READONLY);
    pos = f.position(f2, 1);
 
    if (pos != -1)
      System.out.println("f2 exists in position " + pos);
    else
      System.out.println("f2 doesn't exist in position");
 
    f.close();
    f2.close();
    f3.close();
  }
}

4.4.3 OCI API for BFILEs

This section describes the OCI APIs that you can use with BFILEs.

See Also:

LOB and BFILE Operations

Table 4-5 OCI APIs for BFILEs

Category	Function/ Procedure	Description
Sanity Checking	OCILobFileExists()	Checks if the BFILE exists on the server
	OCILobFileGetName()	Gets the DIRECTORY object name and the file name
	OCILobFileSetName()	Sets the name of a BFILE in a locator without checking if the directory or file exists
	OCILobLocatorIsInit()	Checks whether a LOB Locator is initialized
Open/Close	OCILobOpen() and OCILobFileOpen()	Opens a file. Use OciLobOpen() instead of OCILobFileOpen().
	OCILobIsOpen() and OCILobFileIsOpen()	Checks if the file was opened using the input BFILE locators. Use OCILobIsOpen() instead of OciLobFileIsOpen().
	OCILobClose() and OCILobFileClose()	Closes the file. Use OciLobClose() instead of OciLobFileClose().
	OCILobFileCloseAll()	Closes all previously opened files.
Read Operations	OCILobGetLength2()	Gets the length of the BFILE
	OCILobRead2()	Reads data from the BFILE starting at the specified offset.
	OCILobArrayRead()	Reads data using multiple locators in one round trip.
Operations involving multiple locators	OCILobLocatorAssign()	Assigns a BFILE locator to another
	OCILobLoadFromFile2()	Loads BFILE data from a file into a LOB

Example 4-5 OCI API for BFILEs

static text *selstmt = (text *) "select ad_graphic, ad_composite, ad_sourcetext from print_media where product_id = 1 and ad_id = 1 for update"
sword run_query()
{
  OCILobLocator *f = (OCILobLocator *)0;
  OCILobLocator *f2 = (OCILobLocator *)0;
 
  OCILobLocator *b = (OCILobLocator *)0;
  OCILobLocator *c = (OCILobLocator *)0;
 
  OCIStmt       *stmthp;
  OCIDefine     *defn1p = (OCIDefine *) 0;
  OCIDefine     *defn2p = (OCIDefine *) 0;
  OCIDefine     *defn3p = (OCIDefine *) 0;
 
  ub4            bfilelen;
  ub1            lbuf[128];
  ub8            amt = 15;
  boolean        flag = FALSE;
  ub4            id = 10;
 
  text           filename[128];
  ub2            filename_len;
  text           dirname[128];
  ub2            dirname_len;
 
  CHECK_ERROR (OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &stmthp,
                              OCI_HTYPE_STMT, (size_t) 0, (dvoid **) 0));
 
  /************** Allocate descriptors ***********************/
  CHECK_ERROR (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &f,
                                  (ub4)OCI_DTYPE_FILE, (size_t) 0,
                                  (dvoid **) 0));
 
  CHECK_ERROR (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &f2,
                                 (ub4)OCI_DTYPE_FILE, (size_t) 0,
                                 (dvoid **) 0));
 
  CHECK_ERROR (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &b,
                                  (ub4)OCI_DTYPE_LOB, (size_t) 0,
                                  (dvoid **) 0));
 
  CHECK_ERROR (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &c,
                                  (ub4)OCI_DTYPE_LOB, (size_t) 0,
                                  (dvoid **) 0));
 
  /********** Execute selstmt to get f, b, c ***********************/
  CHECK_ERROR (OCIStmtPrepare(stmthp, errhp, selstmt,
                              (ub4) strlen((char *) selstmt),
                              (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));
 
  CHECK_ERROR (OCIDefineByPos(stmthp, &defn1p, errhp, (ub4) 1, (dvoid *) &f,
                              (sb4) -1, SQLT_BFILE, (dvoid *) 0, (ub2 *) 0,
                              (ub2 *)0, (ub4) OCI_DEFAULT));
  CHECK_ERROR (OCIDefineByPos(stmthp, &defn2p, errhp, (ub4) 2, (dvoid *) &b,
                              (sb4) -1, SQLT_BLOB, (dvoid *) 0, (ub2 *) 0,
                              (ub2 *)0, (ub4) OCI_DEFAULT));
  CHECK_ERROR (OCIDefineByPos(stmthp, &defn3p, errhp, (ub4) 3, (dvoid *) &c,
                              (sb4) -1, SQLT_CLOB, (dvoid *) 0, (ub2 *) 0,
                              (ub2 *)0, (ub4) OCI_DEFAULT));
 
  CHECK_ERROR (OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
                              (CONST OCISnapshot *) NULL, (OCISnapshot *) NULL,
                              OCI_DEFAULT));
 
  /*------------------------------------------------------------------*/
  /*---------------------- Sanity Checking ---------------------------*/
  /*------------------------------------------------------------------*/
 
  /*-------------- Determining Whether a BFILE Exists ----------------*/
  CHECK_ERROR (OCILobFileExists(svchp, errhp, f, &flag));
  printf("OCILobFileExists: %s\n", (flag)?"TRUE":"FALSE");
 
  /*------ Getting Directory Object Name and File Name of a BFILE ----*/
  CHECK_ERROR (OCILobFileGetName(envhp, errhp, f, (text*)dirname, &dirname_len,
                                 (text*)filename, &filename_len));
  printf("OCILobFileGetName: Directory: %.*s Filaname: %.*s \n",
         dirname_len, dirname, filename_len, filename);
 
  /*------------------------------------------------------------------*/
  /*----------------------- Open/Close -------------------------------*/
  /*------------------------------------------------------------------*/
 
  /*----------------------- Opening a BFILE --------------------------*/
  CHECK_ERROR (OCILobFileOpen(svchp, errhp, f, OCI_FILE_READONLY));
  printf("OCILobFileOpen: Works\n");
 
  /*-------------- Determining Whether a BFILE Is Open ---------------*/
  CHECK_ERROR (OCILobFileIsOpen(svchp, errhp, f, &flag));
  printf("OCILobFileIsOpen: %s\n", (flag)?"TRUE":"FALSE");
 
  /*----------------------- Closing a BFILE --------------------------*/
  CHECK_ERROR (OCILobFileClose (svchp, errhp, f));
 
  /*------------ Closing All Open BFILEs with FILECLOSEALL -----------*/
  CHECK_ERROR (OCILobFileCloseAll(svchp, errhp));
 
  /*------------------------------------------------------------------*/
  /*-------------------- BFILE operations ----------------------------*/
  /*------------------------------------------------------------------*/
 
  CHECK_ERROR (OCILobFileOpen(svchp, errhp, f, OCI_FILE_READONLY));
  printf("OCILobFileOpen: Works\n");
 
  /*----------------- Getting the Length of a BFILE ------------------*/
  CHECK_ERROR (OCILobGetLength(svchp, errhp, b, &bfilelen));
  printf("OCILobGetLength: loblen: %d \n", bfilelen);
 
  /*------------------------ Reading BFILE Data ----------------------*/
  CHECK_ERROR (OCILobRead2(svchp, errhp, f, &amt,
                           NULL, (oraub8)1, lbuf,
                           (oraub8)sizeof(lbuf), OCI_ONE_PIECE ,(dvoid*)0,
                           NULL, (ub2)0, (ub1)SQLCS_IMPLICIT));
  printf("OCILobRead2: buf: %.*s amt: %lu\n", amt, lbuf, amt);
 
  /*------------------------------------------------------------------*/
  /*------------- Operations involing 2 locators ---------------------*/
  /*------------------------------------------------------------------*/
 
  /*----------------- Assigning a BFILE Locator ----------------------*/
  CHECK_ERROR (OCILobLocatorAssign(svchp, errhp, f, &f2));
  printf("OCILobLocatorAssign: Works! \n");
 
  amt = 15;
  CHECK_ERROR (OCILobRead2(svchp, errhp, f2, &amt,
                          NULL, (oraub8)1, lbuf,
                          (oraub8)sizeof(lbuf), OCI_ONE_PIECE ,(dvoid*)0,
                          NULL, (ub2)0, (ub1)SQLCS_IMPLICIT));
  printf("OCILobLocatorAssign: OCILobRead2: buf: %.*s amt: %lu\n", amt, lbuf, amt);
 
  /*--------------- Loading a LOB with BFILE Data --------------------*/
  /* Load BLOB from BFILE. Specify amount = UB8MAXVAL to copy till end of bfile */
  CHECK_ERROR (OCILobLoadFromFile2(svchp, errhp, b, f, UB8MAXVAL, 1,1));
  printf("OCILobLoadFromFile2: BLOB case Works\n");
 
  /* Load CLOB from BFILE. Specify amount = UB8MAXVAL to copy till end of bfile.
   * Note that there is no character set conversion here. */
  CHECK_ERROR (OCILobLoadFromFile2(svchp, errhp, c, f, UB8MAXVAL, 1,1));
  printf("OCILobLoadFromFile2: CLOB case Works\n");
 
  /*  Close just f */
  CHECK_ERROR (OCILobFileClose (svchp, errhp, f));
 
  /* Close the rest of bfiles opened */
  CHECK_ERROR (OCILobFileCloseAll(svchp, errhp));
 
  OCIDescriptorFree((dvoid *) b, (ub4) SQLT_BLOB);
  OCIDescriptorFree((dvoid *) c, (ub4) SQLT_CLOB);
  OCIDescriptorFree((dvoid *) f, (ub4) SQLT_BFILE);
  OCIDescriptorFree((dvoid *) f2, (ub4) SQLT_BFILE);
 
  CHECK_ERROR (OCIHandleFree((dvoid *) stmthp, OCI_HTYPE_STMT));
}

4.4.4 ODP.NET API for BFILEs

This section describes the ODP.NET APIs that you can use with BFILEs.

See Also:

OracleBFile Class

Table 4-6 ODP.NET methods in OracleBfileClass

Category	Function/Description	Description
Sanity Checking	FileExists	Checks if the BFILE exists on the server
	FileName	Sets or gets the file name
	DirectoryName	Sets or gets the DIRECTORY object name
Open/Close	OpenFile	Opens a file. Use OPEN instead of FILEOPEN.
	IsOpen	Checks if the file was opened using the input BFILE locators. Use ISOPEN instead of FILEISOPEN.
	CloseFile	Closes the file.
Read Operations	Length	Get the length of the BFILE
	Value	Returns the entire LOB data as a string for CLOB and a byte array for BLOB
	Read	Reads data from the BFILE starting at the specified offset.
	Search	Returns the matching position of the nth occurrence of the pattern in the BFILE.
Operations involving multiple locators	Compare	Compares the values of two BFILEs
	IsEqual	Check if two LOBs point to the same LOB data

4.4.5 OCCI API for BFILEs

This section describes the OCCI APIs that you can use with BFILEs.

In OCCI, the Bfile class enables you to instantiate a Bfile object in your C++ application. You must then use methods of the Bfile class, such as the setName() method, to initialize the Bfile object, which associates the object properties with an object of type BFILE in a BFILE column of the database.

See Also:

Bfile Class

Amount Parameter for OCCI LOB copy() Methods

The copy() method on Clob and Blob enables you to load data from a BFILE. You can pass one of the following values for the amount parameter to this method:

• An amount smaller than the size of the BFILE to load a portion of the data

• An amount equal to the size of the BFILE to load all of the data

• The UB8MAXVAL constant to load all of the BFILE data

You cannot specify an amount larger than the length of the BFILE.

Amount Parameter for OCCI read() Operations

The read() method on an Clob, Blob, or Bfile object, reads data from a BFILE. You can pass one of these values for the amount parameter to specify the amount of data to read:

• An amount smaller than the size of the BFILE to load a portion of the data

• An amount equal to the size of the BFILE to load all of the data

• An amount equal to zero (0) to read until the end of the BFILE in streaming mode

You cannot specify an amount larger than the length of the BFILE.

Table 4-7 OCCI Methods for BFILEs

Category	Function/ Procedure	Description
Sanity Checking	fileExists()	Checks if the BFILE exists on the server
	getFileName()	Gets the file name
	getDirAlias()	Gets the DIRECTORY object name
	setName()	Sets the name of a BFILE in a locator without checking if the directory or file exists.
	isInitialized()	Checks whether a BFILE is initialized.
Open/Close	open()	Opens a file.
	isOpen()	Checks if the file was opened using the input BFILE locators.
	close()	Closes the file.
Read Operations	length()	Gets the length of the BFILE
	read()	Reads data from the BFILE starting at the specified offset.
Operations involving multiple locators	(operator) =	Assigns a BFILE locator to another. Use the assignment operator (=) or the copy constructor.
	Blob.copy() or Clob.copy()	Loads BFILEdata into a LOB

4.4.6 Pro*C/C++ and Pro*COBOL API for BFILEs

This section describes Pro*C/C++ and Pro*COBOL APIs APIs you can use for BFILEs.

See Also:

• Pro*C/C++ Programmer's Guide
• Pro*COBOL Programmer's Guide

Table 4-8 Pro*C/C++ and Pro*COBOL APIs for BFILEs

Category	Function/ Procedure	Description
Sanity Checking	DESCRIBE[FILEEXISTS]	Checks if the BFILE exists on the server
	DESCRIBE[DIRECTORY,FILENAME]	Gets the directory object name and file name
	FILE SET	Sets the name of a BFILE in a locator without checking if the directory or file exists
Open/Close	OPEN	Opens a file.
	DESCRIBE[ISOPEN]	Checks if the file was opened using the input BFILE locators.
	CLOSE	Closes the file.
	FILE CLOSE ALL	Closes all previously opened files.
Read Operations	DESCRIBE[LENGTH]	Gets the length of the BFILE
	READ	Reads data from the BFILE starting at the specified offset.
Operations involving multiple locators	ASSIGN	Assigns a BFILE locator to another
	LOAD FROM FILE	Loads BFILE data into a LOB