NEW TABLE

Table Item
INTRODUCTION	NEW	SET	ATTRIBUTES

You can create a new shell table item with the NEW TABLE command.

Normal Creation

NEW TABLE id [ /Extended|Directory|Parameter ] 
             [ nFields|* 
             [ field0|* field1|* … ]] [ /1 /I /N ] [ /G /L ]

Create a new table. This command can be used to create a simple table, an extended table, a directory table or a parameter table. The fields must be defined and configured before the table can be used (see Defining a table field and Configuring a table field). If the parameters field_X are used, the table can be defined on creation (saving you the SET table DEFINE command).

id

The id to use for the new table item. If an asterisk is used, the id is automatically generated and stored in the local variable #new.

nFields

The number of fields. If nFields is not specified and no table type option (/E|P|D) specified either, then a simple table is created. If a table type option is specified but nFields is not, 1 field is defined. If nFields is an asterisk and the field_X parameter is not specified, then the default number of fields is 1. If field_X field definitions are specified and nFields is an asterisk, then the number of fields is calculated.

field_X

Syntax: {type_X:}name_X or type_X:name_X:count_X

type_X - The data-type (see SET table DEFINE for details). type_X is optional; if it is used, it must be separated from name_X by a colon ':'. The default type for parameter tables (option /Parameter) is NUMBER, otherwise the default is STRING.

name_X: The field name

count_X: repeat name_X count_X times (i.e. name_X will be used to define multiple fields: name_X0 name_X1 name_X2 …).

If field_X is an asterisk, this field is not defined.

/Extended

If specified, an extended table is created.

/Directory

If specified, a soundfile directory table is created. Three fields are added automatically to the specified number of fields:

0=NAME	(Name)
1=BEGIN	(Integer)
2=LENGTH	(Integer)

/Parameter

If specified, a table which can only store numbers (Integer, Number) is created. Memory usage and access is optimized.

/1

This version of NEW TABLE automatically changes the table mode to 'data' if all fields are defined in the NEW TABLE command. If you would like to automatically change to 'data' mode even though not all field definitions have taken place in the NEW TABLE command, please use this /1 option. Note that at least one field must have been defined in this command.

/Initial=n

If specified, memory for n entries is allocated when the first entry is created. This can improve performance immensely, if you know roughly how many entries you are going to use, since memory is allocated once, rather than being incremented regularly (and copied from the old to the new location). Note that this is particularly useful for parameter tables, since the size of the entry is known and therefore all the memory can be accurately allocated.

/N=n

Memory for table entries is allocated in blocks. When the allocated memory runs out, a new block is allocated. You can specify how big the block is in entries (n). The minimum and default value is 50.

/G

Garbage collection. If specified, the item is automatically deleted when exiting the macro.

/L

If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

The table mode is automatically set to 'data', if

1. all fields are defined in the NEW TABLE command; or
2. at least one field is defined in the NEW TABLE command and the flag /1 is specified.

Current Soundfile

NEW TABLE id /Soundfiledirectory [ /G ]

Attach a (temporary) table to the directory table of the current soundfile. To set the current soundfile, use the command BSF SELECT.

/G

Garbage collection. If specified, the item is automatically deleted when exiting the macro

/L

If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Creating a Table as the Copy of an existing Table

NEW TABLE id baseTableItem|baseValueItem [ fieldName ] /Copy [ /All|Tagged [ /tRanspose ]] [ /I /N ]

Create a new table with the same field definitions and configuration settings as the table baseTableItem. You can copy the contents with the flags /All (copy all entries) or /Tagged (copy tagged entries). The tagged state is copied in both cases. The table is transposed if the /R flag is specified. If you want to transpose the base table, all fields must be numeric. Alternatively, you can create a new table and fill it with the values in the value item baseValueItem.

baseTableItem

A table item id.

baseValueItem

A value item id.

fieldName

The base name for field name creation if the option /R is used (e.g. if the base table has two entries and fieldName is fn, the fields fn0 and fn1 are created).

/Copy

Copy the contents of the base item to the new table. This option is mandatory.

/tRanspose

Copy a transposed version of the base item data (i.e. make the rows the columns and the columns the rows). All fields must be numeric. If the /tRanspose option proves too slow for your use-case, the faster EVAL trn should be used instead.

/All|Tagged

Copy either all the entries in baseTableItem (/A) or just the tagged entries (/T). Note that if neither option is specified, only the field definitions are copied. These options are only applicable when copying from a table item.

/Initial=n

If specified, memory for n entries is allocated when the first entry is created. This can improve performance immensely, if you know roughly how many entries you are going to use, since memory is allocated once, rather than being incremented regularly (and copied from the old to the new location). Note that this is particularly useful for parameter tables, since the size of the entry is known and therefore all the memory can be accurately allocated.

/N=n

Memory for table entries is allocated in blocks. When the allocated memory runs out, a new block is allocated. You can specify how big the block is in entries (n). The minimum and default value is 50.