NEW

#itemname := NEW itemtype itemname [ /U|u ]

The command NEW creates a new instance of a shell item. See the individual shell items for the parameters specific to each shell item type. The following is applicable to all NEW commands:

• The argument itemname can be set to '*' if the item should automatically be given a unique name (e.g. NEW FILE * /File).
• The name of a new item is always stored in the variable #NEW if the command was successfully completed, otherwise #NEW is set to '*'.
• An item must be deleted (DELETE name) before another NEW command using the same name can be successfully executed.
• NEW commands can be used in inline statements with the syntax #item = $(NEW itemx paramx). The variable #item is assigned the value of #NEW. Therefore if the command fails, both are assigned the value *.

/U

The option /U sets the multi-protect state, which protects all items created before this command and the new item itself from being deleted. This option can only be used once by a shell. The state is automatically reset when the item which activated the multi-protection is deleted on a macro-level equal/below the creation macro-level.

The option /u sets the single-protection state. The item can then only be deleted using the DELETE command with the option /u (e.g. "DELETE protecteditem /u"

The following example creates a new table with an automatic name and assigns the name to a local variable or exits if the table was not created.

NEW TABLE *
if '$#new' == '*' then
butil msgbox msg ; Failed to create table
exit
end
#t := $#new
$#t * 'my first entry' // append entry to table

You can also use your own name, rather than an automatically generated one. In this case, the code would look like this.

NEW TABLE myTable
if '$#new' == '*' then
butil msgbox msg ; Failed to create table
exit
end
myTable * 'my first entry' // append entry to table

Alternatively, with the inline syntax:

#t := $(NEW TABLE *)
if '$#t' == '*' then
butil msgbox msg ; Failed to create table
exit
end
$#t * 'my first entry' // append entry to table

Please delete all instances created with the new command using the DELETE command.