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
- 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
#NEWif the command was successfully completed, otherwise
#NEWis set to '
- An item must be deleted (
DELETE name) before another
NEWcommand using the same name can be successfully executed.
NEWcommands can be used in inline statements with the syntax
#item = $(NEW itemx paramx). The variable
#itemis assigned the value of
#NEW. Therefore if the command fails, both are assigned the value
- The type of the new shell item. This must be unique (in the item namespace of a shell).
- The name of the new shell item. If this argument is set to the character *, the name is choosen automatically.
- 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 .
- Enable silent error reporting. If specified,
NEWwill generate a warning rather than an error if arguments are missing or it is unable create the new item.
- Garbage collection. If specified, a temporary (or local) item created, which is automatically deleted when exiting the macro.
- 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
DELETEcommand. Note: This option is case-sensitive.
- 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.
- 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