Contents

locks

Keywords: general, variables

A locked variable is a variable that is protected from casual
destruction or modification.  You lock variables using lockvars() and
unlock them using unlockvars().  A few pre-defined variables and macros
such as PI, E, VERSION and redo() are automatically locked at start up.
Most other pre-defined constants and macros are not locked.

It is an error to attempt to assign a value to a locked variable or to a
subscript of a locked variable.

  Cmd> PI <- sqrt(2)
  ERROR: illegal assignment to locked variable near PI <-

  Cmd> a <- run(10); lockvars(a); a[3] <- PI
  ERROR: illegal to assign to subscript of a locked variable near
  a <- run(10); lockvars(a); a[3] <-

If you try to delete a locked variable, it is not deleted and a warning
message (suppressed by 'silent:T') is printed.

  Cmd> delete(a) # delete(a, silent:T) prints nothing
  WARNING: attempt to delete locked variable a

You can force deletion by keyword phrase 'lockedok:T' on delete.

  Cmd> delete(a,lockedok:T); print(a)
  ERROR: argument 1 (a) to print() is not defined

You can unlock a variable using unlockvars().

  Cmd> unlockvars(PI); delete(PI); print(PI)
  ERROR: argument 1 (PI) to print() is not defined

You can test whether variables are locked using islocked().

  Cmd> islocked(E, VERSION, MACROFILES, boxcox, redo)
  (1) T       T       F       F       T

When the header line on a data set or macro in a file readable by
matread() or macroread() contains the work LOCKED, the value returned by
matread() or macroread() is saved as a locked variable.
  Cmd> doit <- macroread("macrofile.txt","doit")
  doit  MACRO LOCKED

  Cmd> list(doit)
  doit            MACRO  (in-line) (locked)

You cannot lock temporary variables (names starting with '@'), special
variables such as CLIPBOARD and GRAPHWINDOWS and a few other variables
such as LASTPLOT and LASTLINE.

  Cmd> lockvars(LASTLINE)
  ERROR: can't lock variable LASTLINE

If you lock a GLM side effect variable such as RESIDUALS or STRMODEL, it
effectively blocks any more GLM commands such as regress(), anova() or
poisson() until the variable is unlocked or deleted.

save() and asciisave() save the locked/unlocked status of a variable, so
when the workspace file is restored, a locked variable is restored as a
locked variable.

restore(workspaceFile, delete:F) will not restore variables with the
same name as existing locked variables.  Unless the locked variable is a
REAL scalar and the value in the file is the same as the current value,
a warning message is printed.

See also 'variables', unlockvars(), lockvars(), islocked().