BUILD_TABLE Function

Creates a table from one or more vectors (one-dimensional arrays).

Usage

result = BUILD_TABLE(' var₁ [alias], ..., var_n [alias] ')

Input Parameters

var_i—A vector (one-dimensional array) variable. If additional vectors are specified, they must contain the same number of elements as var_i. The input variable(s) can be of any data type.

alias—(optional) Specifies a new name for the table column. By default, the input variable’s name is used.

Returned Value

result—A table containing n columns, where n is equal to the number of input variables.

Input Keywords

In_Structure—A scalar string expression that specifies the name of a PV‑WAVE structure to use to create the result table. This structure can either be defined by the user, or obtained from the Out_Structure keyword from a previous BUILD_TABLE call. If user-defined, the tag definitions of this structure must meet the requirements for PV‑WAVE table variables. If no value is specified by In_Structure, PV‑WAVE creates a new named structure, based on the types of the column variables specified in the parameter string. The purpose of this keyword is to allow you to append new rows to an existing table variable.

Output Keywords

Out_Structure—A string variable which receives the name of the PV‑WAVE structure that was used to create the result table. The purpose of this keyword is to allow you to append rows to the result table with subsequent calls to BUILD_TABLE. In this scenario, Out_Structure is used to save the name of the structure created during the first BUILD_TABLE call. This same structure name is used (with the In_Structure keyword) to append rows to the result table.

Discussion

Once created, you can subset the table using the QUERY_TABLE function. Each vector must have the same number of elements. If not, an error message is displayed and the table is not created.

A table is built from vector (one-dimensional array) variables only. You cannot include expressions in the BUILD_TABLE function. For example, The following BUILD_TABLE call is not allowed:

result = BUILD_TABLE('EXT(0:5), COST(0:5)')

However, you can achieve the desired results by performing the array subsetting operations first, then using the resulting variables in BUILD_TABLE. For example:

EXT = EXT(0:5)
COST = COST(0:5)
result = BUILD_TABLE('EXT, COST')

In addition, you cannot include scalars or multidimensional-array variables in BUILD_TABLE.

Note: ASC and DESC are reserved words (used by QUERY_TABLE for direction) and thus are not allowed to be used as variable names or aliases.

Example 1

The following command creates a table consisting of eight columns of data. The data used to create the table has been included in a file. Enter the following command at the WAVE> prompt to restore the data:

(UNIX) RESTORE, !dir+'/data/phone_example.sav'
(WIN) RESTORE, !dir+'\data\phone_example.sav'

The columns are created from data read into PV-WAVE and placed into vector variables.

phone_data = BUILD_TABLE('DATE, TIME, ' + $
   'DUR, INIT, EXT, COST, AREA, NUMBER')

Phone Data Table shows a portion of the resulting table.

Phone Data Table
DATE	TIME	DUR	INIT	EXT	COST	AREA	NUMBER
901002	093200	21.40	TAC	311	5.78	215	2155554242
901002	094700	1.05	BWD	358	0	303	5553869
901002	094700	17.44	EBH	320	4.71	214	2145559893
901002	094800	16.23	TDW	289	0	303	5555836
901002	094800	1.31	RLD	248	.35	617	6175551999
901003	091500	2.53	DLH	332	.68	614	6145555553
901003	091600	2.33	JAT	000	0	303	555344
901003	091600	.35	CCW	418	.27	303	5555190
901003	091600	1.53	SRB	379	.41	212	2125556618

Use the INFO command to view the new table structure, for example:

INFO, /Structure, phone_data
** Structure TABLE_0, 8 tags, 40 length:

`DATE`	`LONG`	`901002`
`TIME`	`LONG`	`93200`
`DUR`	`FLOAT`	`21.4000`
`INIT`	`STRING`	'`TAC`'
`EXT`	`LONG`	`311`
`COST`	`FLOAT`	`5.78000`
`AREA`	`LONG`	`215`
`NUMBER`	`STRING`	`2155554242`

The Structure keyword is used in this example because tables are represented in PV‑WAVE as an array of structures.

The QUERY_TABLE function can be used to retrieve information from this table. For example:

res = QUERY_TABLE(phone_data, ' * Where COST > 1.0')

This query produces a new table containing only the rows where the cost is greater than one dollar.

Example 2

This example demonstrates the use of the optional alias parameter. This parameter lets you specify new names for the columns of the table. By default, the names of the input variables are used as column names.

phone_data1 = BUILD_TABLE('DATE Call_Date,' + $
   TIME Call_Time, DUR Call_Length,' + $
   'INIT, EXT, COST Charge, AREA Area_Code,'+ $
   'NUMBER Phone_Number')

The structure of this table reflects the new column names:

INFO, /structure, phone_data
** Structure TABLE_0, 8 tags, 40 length:

`CALL_DATE`	`LONG`	`901002`
`CALL_TIME`	`LONG`	`93200`
`CALL_LENGTH`	`FLOAT`	`21.4000`
`INIT`	`STRING`	'`TAC`'
`EXT`	`LONG`	`311`
`CHARGE`	`FLOAT`	`5.78000`
`AREA_CODE`	`LONG`	`215`
`PHONE_NUMBER`	`STRING`	`2155554242`