Programming Guide

ALIAS

Sets aliases for a declared or default SELECT cursor

Synopsis

DBMS [WITH CURSOR cursor] ALIAS [column pantherVar
	[, column pantherVar ...]]
 
DBMS [WITH CURSOR cursor] ALIAS [pantherVar [, pantherVar ...]]

Arguments

WITH CURSOR cursor
Name of a declared SELECT cursor. If the clause is not used, Panther uses the default SELECT cursor.

column
Name of column in the database table.

pantherVar
Name of Panther variable to contain the data.

Description

By default, database values are written to Panther variables with the same names as the selected database columns. Use DBMS ALIAS to map a database column or value to any Panther variable.

If a column name is given, it is associated with the variable name that follows it. For example: 

DBMS ALIAS name title, film_minutes length

If the database column name is selected with the default cursor, its value is written to the Panther variable title. If the column film_minutes is selected with the default cursor, its value is written to the Panther variable length. For all other columns selected with the default cursor, the column's value is written to a variable with the same (unqualified) name as the selected column.

If column contains characters not permitted in Panther identifiers, enclose column in quotes to ensure correct parsing. For example: 

DBMS ALIAS "last-name" last_name

The case of column needs to match the setting of the case flag used to initialize the database engine. For example, if the case flag is DM_FORCE_TO_LOWER_CASE, column must be entered in lower case. The case of pantherVar must be the case used to name the Panther variable. If pantherVar does not exist, Panther ignores the column when it executes the SELECT. Refer to "Database Drivers" for details of case setting for each database engine.

If no column arguments are given, the association is positional. For example: 

DBMS ALIAS title_var, , abc

When the above statement is executed, each time values are selected with the default cursor, Panther writes the values of the first and third columns to the Panther variables title_var and abc, respectively. For all other columns selected with the default cursor, Panther writes to a variable with the same (unqualified) name as the selected column. The order of column names in the select statement determines the mapping. Named and positional aliases cannot be assigned in a single statement.

Only one DBMS ALIAS statement is allowed for each cursor. The last DBMS ALIAS statement called is the one currently in effect.

If aliases are declared for a CATQUERY cursor with the HEADING ON option, Panther uses the aliases rather than the column names to build the heading. The alias for a column selected with a CATQUERY cursor can be enclosed in quotes. This permits a column heading to use embedded spaces. For example: 

DBMS DECLARE t_cursor CURSOR FOR \
	SELECT title_id, name, pricecat FROM titles
DBMS WITH CURSOR t_cursor CATQUERY TO FILE t_list
DBMS WITH CURSOR t_cursor ALIAS \
	"Title ID", Name, "Price Category"
DBMS WITH CURSOR t_cursor EXECUTE

Aliasing for a cursor is turned off by executing the DBMS ALIAS command with no arguments. Closing a cursor also turns off aliasing. If a cursor is redeclared without being closed, the cursor keeps the aliases. Aliases do not affect INSERT, UPDATE, or DELETE statements.

The ALIAS command is necessary if the name of a selected column is not a valid Panther variable name, if the application is selecting values from different tables which use the same column name for different values, or if a selection is not a column value, but the value of an aggregate function or select expression.

Example

// Assign named aliases for a declared cursor.
 
DBMS DECLARE x CURSOR FOR \
	SELECT title_id, copy_num, status FROM tapes
DBMS WITH CURSOR x ALIAS \
	title_id code, copy_num copy, status current_status
DBMS WITH CURSOR x EXECUTE
DBMS WITH CURSOR x ALIAS
 
// Set a positional alias for the 2nd and 4th columns.
// Use automatic mapping for the 1st and 3rd columns.
 
DBMS ALIAS , var_x, , var_y
DBMS QUERY SELECT title_id, name, genre_code, release_date \
	FROM titles
 
// Panther will write
//	column title_id     to variable title_id,
//	column name         to variable var_x,
//	column genre_code   to variable genre_code, and
//	column release_date to variable var_y.
 
// Note how the mappings change when the columns are
// listed in another order.
 
DBMS QUERY SELECT name, genre_code, release_date, title_id \
	FROM titles
 
// Panther will write
//	column name         to variable name,
//	column genre_code   to variable var_x,
//	column release_date to variable release_date, and
//	column title_id     to variable var_y.

See Also

CATQUERY, WITH CURSOR