Syntax

  save  shelf-name

You can use save to create a variable that is local in lifetime but global in visibility. This means you can act on that local variable outside the lexical scope in which it occurs, as long as that scope is still executing. To accomplish this, you must first declare a global variable and then, in the appropriate local scope, save that variable. This creates a local variable with the global variable name attached to it:

  global integer row-count

  process
     do xml-parse document
        scan file "myfile.xml"
        output "%c"
     done

  element table
     save row-count
     set row-count to 0
     output "<table border = %"1%">%c</table>"
     output "<p>The table above has %d(row-count) rows."

  element row
     output "<tr>%c</tr>"
     increment row-count

  element cell
     output "<td>%c</td>"

In the code above, the variable row-count is saved in the "table" element rule. It is then a local variable of the "table" element rule, but it has global visibility. We are therefore able to increment it in the "row" element rule.

The principal advantage of using a saved variable rather than just using a global variable directly comes when we encounter recursive structures. Suppose that in our data we have tables within tables. The code above would work for nested tables without modification. When the table rule was called for the nested table, the variable would be saved again. Since save creates a new local variable which simply borrows the global name, no data is lost no matter how deep the recursion. As each level of recursion exits, the local variable at the next level, whose value has not changed, regains the use of the global name, and processing continues.

The local variable created by a save is initialized to the current value of the global with the same name. If the global is a multi-item shelf, the local is initialized as a shelf of the same size with the same values.

When save is applied to a stream shelf, every item on that shelf must be either unattached or closed and attached to a buffer.

save is a variable declaration, not an action. It must be placed with variable declarations at the beginning of a local scope. It cannot have a condition applied to it.

You cannot save a function argument inside a function.

Save with records and OMX variables

Variables of record types and OMX variables are references, so when you save a variable of this type, you are saving the references, not the actual record or OMX component. This means you have a new local reference to the record or OMX, but still only one global copy of the record of OMX itself. Therefore any changes you make to the record or OMX in the scope of the save is made to the global record or OMX, just as if you had not performed a save. On the other hand, any changes you make to the reference itself are local to the scope of the save and the original reference will be restored when the save scope ends.

The following program illustrates the difference:

  declare record greeting
     field stream word

  global greeting meeting
  global greeting parting

  process

     set meeting:word to "Hello"
     set parting:word to "Goodbye"

     output meeting:word || "%n"
     output parting:word || "%n"

     do
        save meeting
        save parting
        local greeting meeting-french
        set meeting-french:word to "Bonjour"
        set meeting to meeting-french
        set parting:word to "Au revoir"

        output meeting:word || "%n"
        output parting:word || "%n"
     done

     output meeting:word || "%n"
     output parting:word || "%n"

The output of this program is as follows:

  Hello
  Goodbye
  Bonjour
  Au revoir
  Hello
  Au revoir

Notice that within the save scope the values of the record referenced by the variable parting are updated directly within the save scope and are therefore permanent and continue after the end of the scope. In the case of the variable meeting however, meeting is changed to reference a locally created record referenced by meeting-french. When the local copy of meeting is destroyed at the end of the save scope, the original variable is restored and it still references the original record, and thus displays its value in the final output statement.

Related Syntax    save-clear    save groups

Related Concepts    Variables

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]