Programming Guide

Defines Panther variables for fetching binary values

DBMS BINARY variable [, variable ...]

variable

Name of binary variable Panther creates. The variable can contain the number of occurrences and/or a length. Refer to the Description for more information.

Many database engines support a binary data type for byte strings and other non-printable data. There are two ways an application can fetch binary values to Panther variables (widgets, LDB variables, or JPL variables):

• To variables created with the DBMS BINARY command.

• To text widgets which have their C Type (c_type) property set to Hex Dec (PV_HEX_DEC). Panther converts the binary data to hexadecimal strings.

The definition for a variable created with DBMS BINARY can include a number of occurrences and/or a length. If a number of occurrences is supplied, it must be enclosed in square brackets. If a variable length is supplied, it must be enclosed in parentheses. If both are supplied, the number of occurrences must be first. Any of the following are permitted:

db_binvar
db_binvar [10] (255)
db_binvar [5]
db_binvar (8)

Any valid Panther variable name is a legal BINARY variable name. The default number of occurrences is 1, and the default length is 255. The maximum length is platform-dependent, based on the platform's maximum length for unsigned integers. Memory is allocated for the occurrences when they are used (that is, when a binary column is fetched).

If an application is selecting a binary column, use DBMS BINARY to create a binary variable for the column. The variable can have the same name as the column, or it can be mapped to the column with ALIAS. Because a binary variable is a target of a SELECT, Panther examines its number of occurrences when determining how many rows to fetch. Therefore, the binary variable should have the same number of occurrences as the other Panther target variables. When searching for target variables, Panther searches among the binary variables before searching among the Panther variables. You are responsible for ensuring that the binary variable names do not conflict with Panther variable names.

Binary variables can also be included in the USING clause of a EXECUTE statement. If no occurrence is given for the variable, the first occurrence is the default.

Once defined, a binary variable is available to the rest of the application. Note that

DBMS BINARY db_binvar[10]
DBMS BINARY timestamp[100]

is the same as

DBMS BINARY db_binvar[10], timestamp[100]

To delete all binary variables, execute DBMS BINARY with no arguments:

DBMS BINARY

Several library functions are provided for accessing and manipulating binary variables. These functions are only available in C. (Refer to the specific functions in this reference for more information.)

// "timestamp" is a binary column and "timeval"
// is a binary variable.

DBMS BINARY timeval
DBMS ALIAS timestamp timeval
DBMS QUERY SELECT id, name, price, timestamp FROM products

DBMS DECLARE upd_cursor CURSOR FOR \
	UPDATE products SET price = ::priceval \
	WHERE id = ::idval and timestamp = ::timeval
DBMS WITH CURSOR upd_cursor EXECUTE \
	USING priceval, idval, timeval

dm_bin_create_occur, dm_bin_delete_occur, dm_bin_get_dlength, dm_bin_get_occur, dm_bin_length, dm_bin_max_occur, dm_bin_set_dlength

---

---