help/protect

   1 NAME
   2     protect - read or set protect status for a variable or named block
   3
   4 SYNOPSIS
   5     protect(var [, sts])
   6     protect(nblk [, sts])
   7
   8 TYPES
   9     var         lvalue
  10     nblk        named block
  11     sts         integer, 0 <= sts < 512
  12
  13     return      null value
  14
  15 DESCRIPTION
  16     With one argument, protect(var) or protect(nblk) returns the current
  17     protection status for var or nblk.
  18
  19     With two arguments, protect(var, sts) or protect(nblk, sts) sets the
  20     protection status for var or nblk to the value sts.  Each nonzero bit
  21     of sts corresponds to one kind of protection as follows:
  22
  23                 sts     protection
  24
  25                   1     no assign to var
  26                   2     no change of value of var
  27                   4     no change of type of var
  28                   8     no error value for var
  29                  16     no copy to var or nblk
  30                  32     no relocation of var or nblk
  31                  64     no assign from var
  32                 128     no copy from var or nblk
  33                 256     protect recursively all components of var
  34
  35
  36     Here "assign" refers to use of '=' as in A = expr to assign the value
  37     of expr to A, and in A = {..., expr, ...} to assign the value of expr
  38     to some component of A, and to the assignments implicit in swap(A, B),
  39     quomod(x, y, A, B), and pre or post ++ or --.
  40
  41     For example, if A is a global variable, then after
  42
  43                 protect(A, 1);
  44
  45     an error state is established if  A = expr  is attempted.  It does
  46     not imply constancy if, for example, the current value of A is a list
  47     or matrix; such a value may be changed by assignments to the elements
  48     of A, or by push or copy commands.
  49
  50     If the current value of A is val, protect(A, 2) will prevent any
  51     assignment to A other than
  52
  53                 A = expr
  54
  55     where expr evaluates to val.
  56
  57     Any such protection of A is cancelled by protect(A, 0).
  58
  59     If A has components as in a matrix or list, components may be
  60     protected independently from each other and from A by stateents like:
  61
  62                 protect(A[0], 1);
  63                 protect(A[1], 2);
  64
  65     "Copy" refers to the use of copy(A, B, ...) or blkcpy(B, A, ...) to
  66     copy A to B.  For example if B is a block, then after
  67
  68                 protect(B, 16);
  69
  70     attempts to copy to B will fail.
  71
  72     The protection status of var refers to var as a variable, not to its
  73     current value: if an operation like var = value is executed it may
  74     change the value of var but not protect(var).
  75
  76     A named block may be referred to by using the blocks() or blk()
  77     functions, or by assigning it to a variable A and then using either
  78     A or *A.  In the latter cases, protect(A, sts) sets the status for
  79     the variable A; protect(*A, sts) assigns the status for the named
  80     block.  For example, protect(*A,16) will prevent any copying to the
  81     named block; protect(A,16) will prevent any copying to the named block
  82     only when it is referred to by A.
  83
  84     The protection provided by sts = 32 prevents relocation of the memory
  85     used by a block, the freeing of a named block, and addition or removal
  86     of one or more elements from a list.  For example, if a block B has
  87     maxsize 256, then after
  88
  89                 protect(B, 32);
  90
  91     copy(A, B) will fail if the copying would cause size(B) to equal or
  92     exceed 256; if B is a named block, blkfree(B) will not be permitted.
  93     If the current value of L is a list, protect(L, 32) prevents the
  94     execution of push, pop, append, remove, insert, and delete with first
  95     argument L.
  96
  97     With bit 8 of sts set, as with
  98
  99                 protect(A, 257);
 100
 101     the protection provided by the lower order bits extends to any
 102     elements A may have, and recursively to any elements of these elements,
 103     etc.
 104
 105     All protection of A as described above is removed by
 106
 107                 protect(A, 0).
 108
 109
 110 EXAMPLE
 111         > A = 27
 112         > protect(A,1)
 113         > protect(A)
 114                 1
 115         > A = 99
 116         No-assign-to destination for assign
 117
 118         > protect(A,2)
 119         > A = 45
 120         Change of value in assign not permitted
 121
 122         > A = 27
 123
 124         > protect(A,4)
 125         > A = 2 + 3i
 126         Change of type in assign not permitted
 127
 128         > protect(A,8)
 129         > A = 1/0
 130         Error value in assign not permitted
 131
 132         > A = mat[4] = {1,2,3,4}
 133         > B = list(5,6,7,8)
 134         > protect(A,16)
 135         > copy(B,A)
 136                 Error 10226
 137         > strerror()
 138                 "No-copy-to destination variable"
 139
 140         > A = blk(0,5)
 141         > protect(A,32)
 142         > copy("abc", A)
 143         > copy("de",A)
 144         Error 10229
 145         > strerror()
 146         "No-relocation destination variable"
 147
 148         > A = list(1,2,3)
 149         > append(A, 4)
 150         No-relocate list for push
 151
 152         > protect(A, 64)
 153         > X = A
 154         No-assign-from source for assign
 155
 156         > protect(A,128)
 157         > copy(A,B)
 158         Error 10225
 159         > strerror()
 160         "No-copy-from source variable"
 161
 162         > mat A[2] = {1, list(2, mat[2])}
 163         > protect(A,257)
 164         > A[1][[1]][1] = 4
 165         No-assign-to destination for assign
 166         > protect(A,256)
 167         > A[1][[1]][1] = 4
 168         > A[1][[1]]
 169
 170         mat [2] (2 elements, 1 nonzero):
 171             [0] = 0
 172             [1] = 4
 173
 174         > A = blk("alpha") = {1,2,3,4}
 175         > protect(A, 0)
 176         > protect(*A, 16)
 177         copy("abc", A)
 178         Error 10228
 179         No-copy-to destination named block
 180
 181 LIMITS
 182     none
 183
 184 LINK LIBRARY
 185     none
 186
 187 SEE ALSO
 188     assign, copy, blk
 189