Programmer Guide/Command Reference/NEW

The NEW command creates a new shell item of the type itemtype and named itemname.

NEW itemtype itemname [ /I ] [ /U|/u ] [ /G ] [ /Z ] [ createargs [ createopts ] ]

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 *.

itemtype

The type of the new shell item. This must be unique (in the item namespace of a shell).

itemname

The name of the new shell item. If this argument is set to the character *, the name is choosen automatically.

createargs

Arguments specifying parameters for the initialization of the new item. The format and meaning of these arguments are depending on the type of the new .

/I

Enable silent error reporting. If specified, NEW will generate a warning rather than an error if arguments are missing or it is unable create the new item.

/G

Garbage collection. If specified, a temporary (or local) item created, which is automatically deleted when exiting the macro.

/U

If specified, the global item protection is enabled. This means all items created before this item (called the protection-master) are protected from being deleted, until the global item protection is disabled, which is done by deleting the protection-master). Protected items can only be deleted using a special option of the DELETE command. Note: This option is case-sensitive.

/u

If specified, the created item is protected from being deleted, until the global item protection is disabled, which is done by deleting the protection-master). Note: This option is case-sensitive.

/z

Use this option, to create a reference to an already existing shell item (also if owned by another shell). For more details read the section about shell items

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

All instances created with the NEW command should be deleted when no longer needed using the DELETE command.