The BitmapObject class provides attributes and methods that enable you to manipulate the images displayed in an image field. For example, when you create an image field on a form, it is similar to an empty picture frame. To display an image in that picture frame, use the BitmapObject's FileHandle attribute to display an image stored in a file.

Setting a BitmapObject attribute does more than change the image field's value. Each time you change the value, OpenROAD executes the implied procedures. For example, when you set the FileHandle attribute to a new value and the BitmapObject is associated with an image field, OpenROAD displays the new image in the field. This simplifies your coding, because you only need to set the attribute.

The BitmapObject class lets you store images either in standard files or in a database. Using your native file system to store images in standard files provides performance advantages. You can use SQL to store and retrieve the file names in a database table. You can then use the BitmapObject attributes and methods that deal with files to manipulate the images from your application.

The disadvantage of storing images in files is that you are responsible for maintaining them (because the images are stored outside of the system). You must ensure that any files you reference from the application actually exist, and you must back up and update the files appropriately. In addition, if you are creating a portable application or using a network, your program must take into account the different conventions for file specifications.

Storing images in the database enables you to take advantage of the DBMS recovery and transaction facilities. In addition, when you use networks, there are no file name transparency problems. However, this approach also has its disadvantages. When images are stored in a database, it is difficult for other programs to access the images and there is extra overhead in using the database instead of the native file system.

For more information about these two BitmapObject features, see How You Can Store Images in a Database and How You Can Store Images in Files.

You can use your file system to store and retrieve images from standard files. To do this, you must create and maintain the bitmap images in files. OpenROAD reads image files in the following formats:

If you have an image stored in another format, you must use a conversion utility to convert the file into one of these valid formats before you use it with OpenROAD.

For more information, see Bitmap File Formats for BitmapObject in the Language Reference Guide.

To store images in a database, use OpenROAD to add them to a table. OpenROAD automatically creates a special bitmap storage table called ii_stored_bitmaps. However, you can create your own bitmap storage table to improve distribution of the images in the database and avoid transaction bottlenecks. For more information about creating your own bitmap storage table, see How You Can Create a Bitmap Storage Table.

Each image in the bitmap storage table is associated with a handle, called a DBHandle, which you use to access the image. For example, to display an image stored in the database, you can set the value of the DBHandle attribute to the DBHandle for that image. OpenROAD then displays the image that is associated with that particular DBHandle. You must store the DBHandles for the images in a separate table from the images themselves.

Use the InsertIntoDB method to add the image to the database table. The InsertIntoDB method adds the image to the table you specify or, if you do not specify a table, to the system table. (To use a bitmap storage table other than the system table, you must set it up as described in How You Can Create a Bitmap Storage Table.)

To add the images to the database, you would perform the following basic steps:

The image is now stored in the database. You can display the image by setting the DBHandle attribute, and you can replace or delete the image, if necessary, with the UpdateInDB or DeleteFromDB methods, respectively.

For a description of updating images in the database, see Update Bitmaps in a Database. For more information about error handling for the InsertIntoDB method, see Working with Images and Text Strings.

To display an image stored in a database, use the DBHandle attribute of the bitmap object that is associated with the image field. Set the value of BitmapObject's DBHandle attribute to the value of the DBHandle for the particular image.

To remove an image from the database, use the DeleteFromDB method. The DeleteFromDB method deletes the image that has the current value of DBHandle attribute.

The DeleteFromDB method returns ER_OK if successful or a nonzero value if there is an error.

For more information about error handling for the DeleteFromDB method, see Working with Images and Text Strings.

To store bitmaps in a database, use OpenROAD to add them to a table. OpenROAD automatically creates a special bitmap storage table, called ii_stored_bitmaps. You can also create your own storage table.

If you create your own bitmap storage table, it must be owned by someone with authority to grant user permissions to use it, and it must have the following columns and data types:

Create this table as a B-tree structure (compressed or not), with the unique key values on picture_id and row_sequence. Be sure to grant the correct permissions.