datastorage.md 3.9 KB

Table of Contents

Overview

If you want to store data for long-term use, such as player data or high scores, you will need to know how to create, find, and store data to variables. Appvars provide the most versatile storage means, while OS strings, picture vars, and Real vars have some specialized commands.

Get(

To get a pointer to a variable's data, use the Get( command, located at [prgm][right][up][up]. If you are using the Grammer token hook, this is renamed to FindVar(.

The syntax is Get("varname". This returns a pointer to the data in Ans, or 0 if it doesn't exist. If the pointer is less than 32768, then it is archived.

Notes

  • The flash page is returned in Ɵ', though it really isn't useful in Grammer.
  • "varname" needs to contain a type prefix. See Data Types for more info.

Examples

Look for appvar MyVar, and:

  • If it doesn't exist, draw "NOT FOUND"
  • If it exists, but is archived, draw "ARCHIVED"
  • If it exists in RAM, draw the first 10 chars

Note that the prefix for appvars can be 5 or U. I'll use 5.

:.0:Return
:Get("5MyVarZ
:If !Z
:Then
:Text(0,0,"NOT FOUND
:Else
:If Z<32768
:Then
:Text(0,0,"ARCHIVED
:Else
:Text(0,0,Z,10
:End
:End
:Dispgraph
:Stop

length(

length( was intended to get the size of a variable, but it is probably more useful than Get(. It takes the same arguments, but it returns the size in Ans, and the pointer in Ɵ'. However, size is returned as -1 (65535) if it doesn't exist.

Notes

  • If the var doesn't exist, the pointer in Ɵ' will NOT be 0. You have to check the size.

Examples

Look for appvar MyVar, and:

  • If it doesn't exist, draw "NOT FOUND"
  • if it exists, draw the size
  • If it exists, but is archived, draw "ARCHIVED"
  • If it exists in RAM, draw "UNARCHIVED"

Note that the prefix for appvars can be 5 or U. I'll use 5. As well, I use the 32-bit store described in the Basic Operations section. This will put the pointer in Z and size in Ɵ

:.0:Return
:length("5MyVar→ZƟ
:If Ɵ=-1
:Then
:Text(0,0,"NOT FOUND
:Else
:Text('0,0:If Z<32768
:Then
:Text(6,0,"ARCHIVED
:Else
:Text(6,0,"UNARCHIVED
:End
:End
:Dispgraph
:Stop

Send(

To create a variable, use the Send( command, located at [prgm][right][up]. If you are using the Grammer token hook, this is renamed to MakeVar(.

The syntax is Send(#,"varname". This returns a pointer to the data

Notes

  • "varname" needs to contain a type prefix. See Data Types for more info.
  • When the data is newly created, it is filled with null bytes.
  • If the var already exists, it will not be overwritten. This also means it won't be resized if needed!
    • If the var already exists as the wrong size, you might cause a crash when you write to it. Always check the variable info with the Get( or length( commands!

Examples

So as an example, suppose we want to create an AppVar of 100 bytes called "MyVar". The prefix for appvars can be 5 or U, and I'll use 5:

.0:Return
:Send(100,"5MyVar
:Stop

Unarchive

Archive

Delvar

Appvars and Programs

Picture Vars

OS Strings

OS Real Vars