Programming Guide

BINARY

Defines Prolifics variables for fetching binary values

Synopsis

DBMS BINARY variable [ , variable ... ]

Arguments

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

Description

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 Prolifics variables (widgets, LDB variables, or JPL variables):

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 Prolifics 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 DBMS ALIAS. Because a binary variable is a target of a SELECT, Prolifics 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 Prolifics target variables. When searching for target variables, Prolifics searches among the binary variables before searching among the Prolifics variables. You are responsible for ensuring that the binary variable names do not conflict with Prolifics variable names.

Binary variables can also be included in the USING clause of a DBMS 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.)

Example

// "timestamp" is a binary column and "timeval" 
// is a binary variable.
 
DBMS BINARY timeval
DBMS ALIAS timestamp timeval
DBMS SQL 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

See Also

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