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 and coroutines

In a program that executes sequentially, the lexical scopes that save a variable always execute in a properly nested way. The state of a saved variable outside the scope and inside the scope are always distinct and cannot be accessed at the same time. If, however, the program executes multiple coroutines that share access to the same global variable, what happens when only one of the coroutines saves the variable?

If the variable is declared as global, the action save has global effect equally visible in all coroutines. All saves must be properly scoped, just as in the case of a sequentially-executing program. If two coroutines try saving the same global variable in overlapping scopes, OmniMark throws a program error at the end of the first scope, before the variable value gets corrupted.

If the variable is declared as domain-bound global, the effect of save is visible only in the coroutine that saves the variable. For any other coroutine, the variable retains the same items it had outside the saving scope. A domain-bound global can be saved in overlapping scopes without any constraints.

The following program demonstrates the difference between a global and a domain-bound global variable:

  global              string s1 initial { "Hello, World!" }
  domain-bound global string s2 initial { "Hello, World!" }
  
  define string source function
     f
  as
     save s1
     save s2
  
     set s1 to "Salut, Monde!"
     set s2 to "Salut, Monde!"
  
     output "Ready.%n"
     output "Within the save scope: " || s1 || " " || s2 || "%n"
  
  
  process
     using input as f
     do
        output #current-input take "Ready.%n"
        output "Outside the save scope: " || s1 || " " || s2 || "%n"
  
        do
           save s1
           save s2
  
           set s1 to "Hola, Mundo!"
           set s2 to "Hola, Mundo!"
           output #current-input take (any ** "%n")
        done
     done

The output of this example is

  Outside the save scope: Salut, Monde! Hello, World!
  Within the save scope: Hola, Mundo! Salut, Monde!

Also note that, if we were to shorten the last output line in the program to output #current-input, the function would end before the using input as scope. The program would then fail with errors.

Save with records and opaque data type variables

Variables of record types and opaque data types are references, so when you save a variable of this type, you are saving the references, not the actual record or opaque variable. This means you have a new local reference to the record or opaque variable, but still only one global copy of the record of variable itself. Therefore any changes you make to the record or variable in the scope of the save is made to the global record or variable, 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 and Constants

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