$STORAGE (ObjectScript)

Synopsis

$STORAGE
$S

Description

$STORAGE returns the number of bytes available for local variable storage in the current process partition. The initial value of $STORAGE is established by the value of $ZSTORAGE, the maximum amount of memory available to the process. The larger the $ZSTORAGE value (in kilobytes), the larger the $STORAGE value (in bytes). However, this relationship between $ZSTORAGE and $STORAGE is not a simple 1:1 ratio.

The $STORAGE value is affected by the following operations:

• $STORAGE decreases as local variables are defined in the local variable space, for example, by using the SET command. The decrease in $STORAGE corresponds to the amount of space required to store the value of the local variable; the size of the name of the local variable has no effect on $STORAGE, but the number of subscript levels does affect $STORAGE. The $STORAGE value increases as local variables are removed, for example, by using the KILL command.

• $STORAGE decreases when you issue a NEW command. NEW establishes a new execution level; space set aside for local variables (whether or not used) at the previous execution level is not available at the new execution level. The $STORAGE value increases when you issue a QUIT command to exit an execution level.

The $STORAGE value is not affected by setting process-private globals, global variables, or special variables. The $STORAGE value is not affected by changing namespaces.

The $STORAGE special variable cannot be modified using the SET command. Attempting to do so results in a <SYNTAX> error.

Examples

The following example shows how $STORAGE becomes smaller when $ZSTORAGE is set to a smaller value. Note that the relationship (ratio) between these two values is variable:

  SET $ZS=262144
  WRITE "$ZS=",$ZS," $S=",$S," ratio=",$NORMALIZE($S/$ZS,3),!
  FOR i=1:1:10 {
          IF $ZS>32768 {SET $ZS=$ZS-32768
          WRITE "$ZS=",$ZS," $S=",$S," ratio=",$NORMALIZE($S/$ZS,3),!
          }
  }

The following example shows how $STORAGE decreases as local variables are assigned, and increases when local variables are killed:

  WRITE "$STORAGE=",$S," initial value",!
  FOR i=1:1:30 {SET a(i)="abcdefghijklmnopqrstuvwxyz"
    WRITE "$STORAGE=",$S,! }
  KILL a
  WRITE !,"$STORAGE=",$S," after KILL",!

The following example shows how the number of subscript levels of an assigned local variable affect $STORAGE:

  WRITE "No subscripts:",!
  SET before=$S
  SET a="abcdefghijklmnopqrstuvwxyz"
  WRITE " memory allocated ",before-$S,!
  KILL a
  WRITE "One subscript level:",!
  SET before=$S
  SET a(1)="abcdefghijklmnopqrstuvwxyz"
  WRITE " memory allocated ",before-$S,!
  KILL a(1)
  WRITE "Nine subscript levels:",!
  SET before=$S
  SET a(1,2,3,4,5,6,7,8,9)="abcdefghijklmnopqrstuvwxyz"
  WRITE " memory allocated ",before-$S,!
  KILL a(1,2,3,4,5,6,7,8,9)

The following example shows how $STORAGE decreases (becomes unavailable at that level) as NEW establishes a new execution level:

   WRITE "increasing levels:",!
   FOR i=1:1:10 {WRITE "$STORAGE=",$S,! NEW }

The following example shows how $STORAGE decreases as local variables are assigned until it enters low memory state, issuing a <STORE> error. The <STORE> error is caught by a CATCH block that invokes the StoreErrorReason() method to determine what caused the error. Note that entering the CATCH block consumes a significant amount of storage. Once in the CATCH block, this example allocates one more variable.

  TRY {
    WRITE !,"TRY block",!
    SET init=$ZSTORAGE
    SET $ZSTORAGE=456
    WRITE "Initial $STORAGE=",$STORAGE,!
    FOR i=1:1:1000 {
       SET pre=$STORAGE
       SET var(i)="1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
       IF $STORAGE<0 {WRITE "var(",i,") negative memory=",$STORAGE,! }
       ELSEIF pre<$STORAGE {WRITE "var(",i,") new allocation $S=",$STORAGE,! }
       ELSE {WRITE "var(",i,") $S=",$STORAGE,! }
    }
  }
  CATCH myexp {
      WRITE !,"CATCH block exception handler",!!
      WRITE "Name: ",$ZCVT(myexp.Name,"O","HTML"),!
        IF myexp.Name="<STORE>" {WRITE "store error reason=",
                                 $SYSTEM.Process.StoreErrorReason(),! }
      WRITE "$S=",$STORAGE,!
      SET j=i
      SET var(j)="1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
      WRITE "var(",j,") added one more variable $S=",$STORAGE,!
      SET $ZSTORAGE=init
      RETURN
  }

See Also

• $ZSTORAGE special variable

• Local variables