Introduction to globally-stored data


The SPFLite macro facility provides functions which allow you to save numeric and/or string data from your macro. This saved data can be retrieved later in the same macro, in a subsequent new execution of the same macro, or by any other macro executing later.


See Function Details for information on calling these functions.


Globally-stored data can enable the creation of a set of related macros and provide a means for them to communicate with each other. It could also be used to store "state-like" information for a single macro that is executed repeatedly over the course of an edit session.


The stored values are maintained only for the duration of the current SPFLite session. You may do multiple Edit/Save functions on different files, and the global data will be maintained. Globally-stored data will be discarded when SPFLite is terminated.


Globally-stored data is not "persistent" in the way that certain Profile and edit settings are when you have STATE ON in effect. Globally-stored data, and STATE information, are two completely different concepts.


If you really needed globally-stored data to persist across SPFLite executions, it is possible you could write out the data to a file and then read it back in later, using file-management services provided by thinBasic. We haven't experimented with this ourselves, but you're welcome to try. (If you do, let us know how it works out for you.)


Or you could use the SPFLite SET variable support to retain data using the Get_SetVar$ and Set_SetVar functions.


Also be aware that globally-stored data is only "global" within a given SPFLite execution. If you have multiple instances of SPFLite running in Windows, each one has its own copy of globally-stored data for its own execution instance. The global data is not shared across multiple SPFLite instances.


The data is held in "storage pools" as a series of key/data pairs. (Some people refer to that as a "map" or "associative storage", if that helps.)  The keys may be any strings of your choosing. There are two global storage pools. One is for storing string data, and the other is for storing numeric data.


Like global variables in any other language, globally-stored values can be a good thing if handled carefully, but could cause problems if misused in a poorly designed macro, for reasons well-known to experienced software developers. Persistent data sometimes causes unexpected side effects, which you need to be aware of, and plan for. Generally, you should only use globally-stored data if conventional local variables are not enough. They should be used sparingly, and only as a last resort. (As they say, be careful what you wish for.)


Sub-Tables


Since there are just two Global pools (String and Numeric), you may have multiple requirements for storage of a single type. This is handled by using an Optional sub-table number to create unique groupings. You may use any number you like to identify a table, and the same key-names may occur in different subtables. The Table-number is entered as an optional first parameter to the Set_Gbl, Get_Gbl and Reset_Gbl functions. If the operand is omitted, a value of zero is assumed.


Examples:

SET_GBL_NUM("KEY1", 12)      will store 12 as a value for the key KEY1 in the default Table zero


SET_GBL_NUM(4, "KEY1", 15)   will store 15 as a value for the key KEY1 in Table 4


GET_GBL_NUM("KEY1")          will return 12 as a value for the key KEY1 from the default Table zero


GET_GBL_NUM(2, "KEY1")       will return 0 as a value since it asked for a value from Table 2 which was never used.


GET_GBL_NUM(4, "KEY1")       will return 15 as a value for the key KEY1 from Table 4




Undefined keys and deletion of global storage


If you request the value of an undefined key, the functions will return default values of 0 (for Get_Gbl_Num) and a null string (for Get_Gbl_Str$). Thus, it is not necessary to "initialize" global storage if these default values are sufficient. 


You can also use the fact that an undefined global number returns a zero value as a "flag" showing that some (other) global value needed to be initialized. Recalling that FALSE is the same thing as zero, here is an example of how to do that:


       IF GET_GBL_NUM("INITIALIZED") = FALSE THEN

               SET_GBL_STR ("MY-STR-VAR", "some string value")

               SET_GBL_NUM ("MY-NUM-VAR", some-numeric-value)

               SET_GBL_NUM ("INITIALIZED", TRUE)

       END IF


At present, there is no way to delete an individual key/value pair from a storage pool, once it's defined. To achieve the effect of a deletion, you can store a zero or null value. If it's necessary to determine whether a zero or null is an actually-stored value or just the default value returned when querying for an undefined key, you can check the return code. Querying for a defined key will produce a return code of 0, and querying for an undefined key will produce a return code of 8. You can delete every global number or string using the functions using Reset_Gbl_Num and Reset_Gbl_Str. These two functions also enable you to delete only a specific sub-table. See the Function details for further assistance.



Example


If you wanted to store the last modified date for the current edit file, you could do so by issuing:


Set_Gbl_Str(Get_FileName$, Get_FileDate$)


This would create a global variable with a key equal to the filename, and a value equal to the file's modification date. At some future time this macro, or some other macro, could retrieve this particular date for the file by issuing:


Date-var = Get_Gbl_Str$("the file name")


If still had the same data file actively being edited, you could do this:


Date-var = Get_Gbl_Str$(Get_FileName$)


There is no limit to the number of global variables, or the size of the saved strings, other than available system memory.



Available global functions


See the relevant section in Function Details for additional information on these functions.


Set_Gbl_Num([TblNum,]key-str, value-num)

Stores the value-num under the key specified by key-str. If a key matching the contents of key-str already exists, the numeric value it was previously associated with is replaced with the new value-num. If a key matching the contents of the key-str does not already exist, it is created.


Set_Gbl_Str([TblNum,]key-str, value-str)

Stores the value-str under the key specified by key-str. If a key matching the contents of key-str already exists, the string value it was previously associated with is replaced with the new value-str. If a key matching the contents of the key-str does not already exist, it is created.


num-var = Get_Gbl_Num([TblNum,]key-str)

Returns the numeric value associated with key-str. If the key does not exist, zero is returned, and an error is stored in the RC and Msg$ variables.


str-var = Get_Gbl_Str$([TblNum,]key-str)

Returns the string value associated with key-str. If the key does not exist, a null (empty) string is returned, and an error is stored in the RC and Msg$ variables.


num-var = Get_Gbl_Str_Count

Returns the current number of variables stored in the String pool.


num-var = Get_Gbl_Num_Count

Returns the current number of variables stored in the Numeric pool.


str-var = Get_Gbl_Str_Name$(index-num)

Returns the key name of the specified item in the String pool.

index-num must be a number in the range of 1 through the the value of Get_Gbl_Str_Count.


The keys stored in the String pool are not stored in any predicable order. To find the location of a given key in the pool, you must do a linear search from beginning to end until it is found. Pool management is done using software outside the control of SPFLite. Adding new entries to a pool may change the index of previously stored entries. If this happens, you may need to perform a new search to redetermine the location of a previously-located key.


str-var = Get_Gbl_Str_TableName$(index-num)

Returns the Table-number and key name of the specified item in the String pool.

index-num must be a number in the range of 1 through the the value of Get_Gbl_Str_Count.


The str-var returned contains the table-number preceding the key name, separated by a comma. e.g. a value like 4,KEYWORD.


The table number is easily accessed via VAL(str-var)

The keyname can be accessed via  REMAIN$(str-var, ",")


See also the note above re: order of entries.


str-var = Get_Gbl_Num_Name$(index-num)

Returns the key name of the specified item in the Numeric pool.

index-num must be a number in the range of 1 through the the value of Get_Gbl_Num_Count.


The keys stored in the Numeric pool are not stored in any predicable order. To find the location of a given key in the pool, you must do a linear search from beginning to end until it is found. Pool management is done using software outside the control of SPFLite. Adding new entries to a pool may change the index of previously stored entries. If this happens, you may need to perform a new search to redetermine the location of a  previously-located key.


str-var = Get_Gbl_Num_TableName$(index-num)

Returns the Table-number and key name of the specified item in the String pool.

index-num must be a number in the range of 1 through the the value of Get_Gbl_Str_Count.


The str-var returned contains the table-number preceding the key name, separated by a comma. e.g. a value like 4,KEYWORD.


The table number is easily accessed via VAL(str-var)

The keyname can be accessed via  REMAIN$(str-var, ",")


See also the note above re: order of entries.


num-var = Reset_Gbl_Num

Clears the entire Gbl_Num storage area. Returns True is successful, or False if the Clear fails.


num-var = Reset_Gbl_Str

Clears the entire Gbl_Str storage area. Returns True is successful, or False if the Clear fails.

Created with the Personal Edition of HelpNDoc: Why Microsoft Word Isn't Cut Out for Documentation: The Benefits of a Help Authoring Tool