Mike Kadow · Aug 13, 2016 3m read

NewBie's Corner Session 17 New command

NewBie's Corner Session 17 New command

Welcome to NewBie's Corner, a weekly or biweekly post covering basic Caché Material.

New command

The New command limits a variable's scope or range of use. In theory the New command is simple, in reality the New command is powerful and needs to be respected and understood.  In Caché ObjectScript and MUMPS an entire chapter is devoted to it.

There are three variations of the New command:

When used without variables

When used with variable(s)

When used with variables in parenthesis

New command used without variables

Set X=1                                 ; X is set to 1
New                                      ; All variables are new
Write  X                                ; X no longer has a value because was Newed
Quit                                       ; Original values of the New command are restored
Write X                                 ; no X has it original value

From the point of the New command until the Quit command, all variables created will be new. Old variables and their values are gone but will be restored when the Quit command is encountered.

New command used with variables

New X,Y

When the new command is used with variables, only the variables specified are Newed. No other variables are affected.

This form of the New command is hard  to maintain, when editing the code you must always remember to add any variables you create to the new command.

New command used with variables in parenthesis.

New (X,Y)

With this form of the new command, all variables except those in the parenthesis will be new. The old values of these variables are gone and will be restored when a Quit command is encountered. The variables inside the parenthesis are not affected.

This form of the New command has the advantage over the previous one in that if new variables are added later they will automatically be Newed unless explicitly included within the parenthesis.

New command may exhaust Memory

Used improperly the New command can easily exhaust available memory.

For I=1:1:10000 New X Do
 . Set X=I
 . Write !,X

This example demonstrates improper use of the New command. The variable X is continually “Newed” until memory is exhausted.

For I=1:1:10000 Do
. New X
 . Set X=I
 . Write !,X

Here is the same example using the New command properly.

New command warnings

The ramification of the New command is far reaching and needs to be used wisely. Without the New command, all variables are accessible to all routines that run in the same process. The New command is an attempt to limit this scope. It may be of good use in utility routines and functions that should not change the value of any previously defined variables. You need to experiment and run tests with this command to understand it.

--Mike Kadow

If you have a comment, please respond through the InterSystems Developer Community, don't send me private email, unless of course you wish to address me only.

See "Newbie's Corner Index" for an index of all NewBies' Posts

0 475
Discussion (7)5
Log in or sign up to continue

One difficulty when converting old "dotted" code to use the new curly brackets is that New applies to the current dot level - same as if the dot level was a routine - but not the scope of the curly brackets containing the New.

For  all the InterSystems Caché newcomers I would strongly  recommend using curly braces syntax instead of dot syntax for stack management. 

So this:

For I=1:1:10000 New X Do

 . Set X=I

 . Write !,X

Can be rewritten to:

For I=1:1:10000 New X Do {

        Set X=I

        Write !,X


This is VERY important IMHO - purely from the perspective of maintainability by non-Msters, like Java and .Net programmers. They ALL understand curly braces, but they are ALL scratching their heads and reading manuals for the dot syntax. And then swearing to never touch Caché again.

Personally I only use dot syntax these days if iterating down through a deep global structure with multiple subscript levels, where I think it makes the code a little easier to read and I am an old M guy so it is second nature. But that is a very isolated case and not often used these days in the object/SQL world. HH

Nice article, Mike. 2 cents here though for Caché newbies - the need for the New command more or less went away with the move to class methods and implicit scoping of their variables.

A common use of the NEW command is to protect %variables. Local variables starting with % are accessible within procedures such as methods even if they are created outside the scope of that procedure. If you want to use % variables within code without worrying about them being previously defined for some other purpose use a NEW command to preserve any existing value they may have. When you exit the stack level where the NEW command was used any previous value for the variable is restored.

Also note, the NEW command does not just preserve the simple unscripted values of values, it preserves the all subscripts of the variable as well.


Test     ;
         Set x="Before New"
         For i=1:1:10 set x(i)=i
         ZW x
         Write !
         New x
         Set x="After NEW"
         ZWrite x
d Test
x="Before New"
x="After NEW"

I appreciate all the comments, and will reply:

To all, I will have a session on Curly Braces when I talk about Structured Programming, I am trying to take things one at a time and not get ahead of myself.

Ray, good comment, I appreciate it. There are a number of problems converting from the dot structure to the Curly Braces, and I plan on covering that.

Evgeny, I too suggest using curly braces, however, if you are a NewBie in a team that uses the dot syntax,  I suggest using what in common practice in the team. The old structures have some very strong proponents and I would not suggest a NewBie buck the trend. It would be good for the NewBie to learn the older ways as well.

Andre, good comments, thank you. I too learned the dot structure and am comfortable with it. Thank you for your mention of Classes doing away with the New command. But bear in mind, many readers of the Developer Community have never used Classes and in their current jobs will never use them. I am writing for all MUMPS/Cache users, from the older to the newer. MUMPS/Cache is evolving. 

Edward, your comments are interesting. I would be careful using the New command on % variables. I would suggest an Application Programmer never set a % variables or use a New command on them (with the exception of SQL variables). When using the New command on % variables please be sure you know the ramifications of what you are doing.

As far as the New command affecting Arrays and all subscripts of arrays, that is true, but only if the New command is used on the top level of the Array. The New command does not work when used on a subscripted variable, ie: New Variable(2)

Bhaskar, sorry I seemed to have missed your comment. When I made the statement of Application Programmer not Newing % variables, I did not consider SQL variables. That represent an exception to my statement, sorry for the omission. Thanks for the reference to the InterSystems documentation.