External Vars Tutorial

[FinaleTI]

1) Appvars and Programs
Appvars and programs have just about the same structure when accessed through Axe. They can have names up to 8 characters in length, that do not start with a number. Appvars can contain lowercase letters in their name, and while programs can, it is more common practice for them to have all uppercase names. This is because if a program contains lowercase letters in its name, it cannot be run from the homescreen.

To access an appvar:

GetCalc("appvAPPVAR")→Pointer

Where 'APPVAR' is to be substituted with the name of the appvar you want to access, and Pointer is where you want the data to point to.
For example:

GetCalc("appvAPPVAR")→A

This stores the location in RAM of the appvar APPVAR to the pointer A. You can then access data in the appvar by using pointers as you normally would.

GetCalc("appvAPPVAR")→A
1→{A}

The code above would store 1 to the first byte of the appvar APPVAR.
The code above will only work if the appvar exists and is in the RAM.

Now, if your appvar doesn't exist, you can easily create it by adding a second argument to your GetCalc() command.

GetCalc("appvAPPVAR",Size)→Pointer

Where Size is the size in bytes of the appvar you want to create.

If the appvar exists, but is in the archive, there are a number of things you can do.
You could unarchive it, but if you are only going to read data from it, this is not the best way to do it.

UnArchive "appvAPPVAR"

Most of the time if you do this, you'll have to end up archiving it when you're done with it.

Archive "appvAPPVAR"

This can take more and more time if you haven't GarbageCollected recently, though. However, this does allow you to save your data in the archive.

If you simply want to read data from an archived appvar, then you could copy it to a file.

GetCalc("appvAPPVAR",File)

Where File is the token for a Y-Var (Y₀-Y₉).

Once the appvar is copied to a file, you can read from it like a pointer.

GetCalc("appvAPPVAR",Y₀)
{Y₀}→A

This would store the first byte of your appvar to the pointer A.

Once you no longer need an appvar, you can simply delete it.

DelVar "appvAPPVAR"

This will only work if the appvar is in the RAM. If you copied your appvar to a file, you don't need to worry about deleting a file, as ending the program will take care of clearing the file for you. In addition, you can copy an appvar to a file that you previously used with no adverse effects.

GetCalc("appvAPPVAR",Y₀)
GetCalc("appvAPPVAR2",Y₀)

This would copy the appvar APPVAR to file Y₀, then copy the appvar APPVAR2 to file Y₀. Accessing file Y₀ would then allow you to access the data in APPVAR2.

Please note that data cannot be stored to files, merely read from files.


Programs can be accessed exactly the same way as appvars, except that you use the 'prgm' token instead of the 'v' you get from [2nd]+[8] (which becomes 'appv' with the Axe Tokens).

2) Real Variables
Accessing real vars is fairly easy to do, actually.
First, getting the pointer to a real var is:

GetCalc("varA")→Pointer

Where A can be substituted with any real var, A-θ, and Pointer is the where you want the data to point to.

Note: If you are using an older version of Axe (pre 0.5.3), then please read the below message. Otherwise, skip it, since it no longer applies, and real vars function like any other external var, pointer-wise.
Now, the tricky part is accessing the data in a real var. Simply doing:

GetCalc("varA")→P
1→float{P}

will not give you proper results. In fact, it will render the variable A invalid until you overwrite it properly, whether inside or outside the Axe program.

The correct offset for accessing a real var is Pointer-2. This is because currently (as of Axe 0.5.2) GetCalc() accounts for the size bytes of a variable, but real vars have no size bytes. Thus, the pointer is offset by 2. This may be fixed in future versions, but until that is stated, stick with Pointer-2 for real vars.

GetCalc("varA")→P
1→float{P-2}
End Note

For Axe 0.5.3 and later, the bug with size bytes always being accounted for no longer exists, so the following is the code you should use:

GetCalc("varA")→P
1→float{P}

This code will store one to the real var A, and you can see that now outside of the Axe program. You can store integers from 0-65535 to real vars using Axe, as Axe only supports two byte numbers. Note: You don't need to put a ^r after the float command if you are storing a two byte number.
The 'var' token is the 'u' you get from [2nd]+[7] (it becomes 'var' with the Axe tokens).

3) Strings
Strings are actually dealt with in the same way as programs and appvars, storage-wise. The only difference is how you access them.

If you want to use Str0-Str9, you simply use:

GetCalc("StrX")→Pointer

Where StrX is any token from Str0 to Str9. You can also create a string of a certain size by doing:

GetCalc("StrX", Size)→Pointer

Pretty simple, right?

4) Hacked variables
Now here's the fun begins. Say you don't want to touch Str0-Str9, but you need a String for whatever reason. Why not use a hacked variable? For those who don't know what a hacked variable is, the OS only includes the tokens for X amounts of vars, like 10 pictures, or 10 strings. But it actually supports up to 255 different pictures, strings, or whatever other var! These don't have tokens like Str99, so they will show up as a seemingly random token, that may look exactly like another token, but they serve a very different function. These hacked tokens function exactly the same as the normal ones. In Hybrid BASIC games, using hacked pictures is actually a fairly common procedure, since it allows for more graphics easily.

In order to use a hacked variable, it's not as straight forward as a normal one, but it's not really that difficult either. Just different.

For the purposes of this lesson, we'll be using Str1 as a static pointer for our hacked names, but you can just as easily place the data in the GetCalc() statement.

For example, the lesson will present the data like this:
[015D]"M"→Str1
GetCalc(Str1)→P

But you can just as easily do this:
GetCalc([015D]"M")→P
and it should still work correctly.

I've broken down the next section based on what type of var you're looking to use, so find it and read the section.

Hacked Pictures
So you wanna use a hacked picture? That's simple enough.
[0760]Data(#,0)→Str1
# here represents the number of the picture you want to use. Keep in mind that 0 is Pic1, 1 is Pic2, etc., with 10 being Pic0. 11 and up are the hacked pics, and they will use odd tokens to represent themselves in the memory menu.
Once you have your name, getting a pointer is as simple as:
GetCalc(Str1)→Pointer

And creating the picture is as simple as:
GetCalc(Str1, Size)→Pointer


Hacked Strings
Coming soon...



5) Accessing Arbitrary Variables (courtesy of squidgetx)
Copy("HI",L₁+1,2)
0->{L₁+3}
_E15->{L₁}
GetCalc(L₁)->A

It does the same thing as GetCalc("appvHI")->A, but I'm sure you can think of many applications of this method instead (shells and mem readers come to mind). You can use 05 to get a program or 06 to get a protected program (instead of $15). Other prefixes you may be able to use are (taken from the SDK. also I haven't tested all of these and would be wary if you tried GetCalc'ing an application for example)

Data Types:
00h Real
01h List
02h Matrix
03h Equation
04h String
05h Program
06h Protected Program
07h Picture
08h Graph Database
0Bh New EQU  
0Ch Complex
0Dh Complex
14h Application
15h AppVar
17h Group

This could be taken as a little confusing, so let's break this down a little bit.


Copy("HI",L₁+1,2)
This line copies the name of the variable (in this case, "HI") to L₁+1.

0->{L₁+3}
This line adds the null byte or terminating zero to the end of the name string starting at L₁+1. Where 3 is would be the length of the variable name + 1.

_E15->{L₁}
This line stores the type byte of the variable to L₁. In this case, it's denotating an appvar. The _E means the number that follows is the hexadecimal equivalent, so any of the hex numbers from the above list would work here in place of the 15.

GetCalc(L₁)->A
This uses the string you just constructed at the beginning of L₁ to create the variable.

[Deep Thought]

Nice, it seems pretty clear so far, but I think it just goes a bit fast between topics.

And this is probably my problem, but there are weird chars appearing between lines

[Michael_Lee]

Yeah, I opened it with notepad, and I'm seeing a lot of Chinese characters appearing.

Is there a specific way we're supposed to view the text document?

[FinaleTI]

Does it show up properly now?

1) Appvars and Programs

Spoiler for Hidden:

Appvars and programs have just about the same structure when accessed through Axe. They can have names up to 8 characters in length, that do not start with a number. Appvars can contain lowercase letters in their name, and while programs can, it is more common practice for them to have all uppercase names. This is because if a program contains lowercase letters in its name, it cannot be run from the homescreen.

To access an appvar:

Code: Select All | Copy To Clipboard

1	GetCalc("appvAPPVAR")→Pointer

Where 'APPVAR' is to be substituted with the name of the appvar you want to access, and Pointer is where you want the data to point to.
For example:

Code: Select All | Copy To Clipboard

1	GetCalc("appvAPPVAR")→A

This stores the location in RAM of the appvar APPVAR to the pointer A. You can then access data in the appvar by using pointers as you normally would.

Code: Select All | Copy To Clipboard

1 2	GetCalc("appvAPPVAR")→A 1→{A}

The code above would store 1 to the first byte of the appvar APPVAR.
The code above will only work if the appvar exists and is in the RAM.

Now, if your appvar doesn't exist, you can easily create it by adding a second argument to your GetCalc() command.

Code: Select All | Copy To Clipboard

1	GetCalc("appvAPPVAR",Size)→Pointer

Where Size is the size in bytes of the appvar you want to create.

If the appvar exists, but is in the archive, there are a number of things you can do.
You could unarchive it, but if you are only going to read data from it, this is not the best way to do it.

Code: Select All | Copy To Clipboard

1	UnArchive "appvAPPVAR"

Most of the time if you do this, you'll have to end up archiving it when you're done with it.

Code: Select All | Copy To Clipboard

1	Archive "appvAPPVAR"

This can take more and more time if you haven't GarbageCollected recently, though. However, this does allow you to save your data in the archive.

If you simply want to read data from an appvar, then you could copy it to a file.

Code: Select All | Copy To Clipboard

1	GetCalc("appvAPPVAR",File)

Where File is the token for a Y-Var (Y₀-Y₉).
as of Axe 0.4.6 using files is a little limited, but they are supposed to become more flexible in future versions.
Once the appvar is copied to a file, you can read from it like a pointer.

Code: Select All | Copy To Clipboard

1 2	GetCalc("appvAPPVAR",Y0) {Y0}→A

This would store the first byte of your appvar to the pointer A.

Once you no longer need an appvar, you can simply delete it.

Code: Select All | Copy To Clipboard

1	DelVar "appvAPPVAR"

This will only work if the appvar is in the RAM. If you copied your appvar to a file, you don't need to worry about deleting a file, as ending the program will take care of clearing the file for you. In addition, you can copy an appvar to a file that you previously used with no adverse effects.

Code: Select All | Copy To Clipboard

1 2	GetCalc("appvAPPVAR",Y0) GetCalc("appvAPPVAR2",Y0)

This would copy the appvar APPVAR to file Y₀, then copy the appvar APPVAR2 to file Y₀. Accessing file Y₀ would then allow you to access the data in APPVAR2.

Please note that data cannot be stored to files, merely read from files.


Programs can be accessed exactly the same way as appvars, except that you use the 'prgm' token instead of the 'v' you get from [2nd]+[8] (which becomes 'appv' with the Axe Tokens).

2) Real Variables

Spoiler for Hidden:

Accessing real vars is fairly easy to do, actually.
First, getting the pointer to a real var is:

Code: Select All | Copy To Clipboard

1	GetCalc("varA")→Pointer

Where A can be substituted with any real var, A-θ, and Pointer is the where you want the data to point to.

Now, the tricky part is accessing the data in a real var. Simply doing:

Code: Select All | Copy To Clipboard

1 2	GetCalc("varA")→P 1→float{P}

will not give you proper results. In fact, it will render the variable A invalid until you overwrite it properly, whether inside or outside the Axe program.

The correct offset for accessing a real var is Pointer-2.

Code: Select All | Copy To Clipboard

1 2	GetCalc("varA")→P 1→float{P-2}

This code will store one to the real var A, and you can see that now outside of the Axe program. You can store 0-65535 to real vars using Axe, as Axe only supports two byte numbers. Note: You don't need to put a ^r after the float command if you are storing a two byte number.
The 'var' token is the 'u' you get from [2nd]+[7] (it becomes 'var' with the Axe tokens).

[Michael_Lee]

Yup.  It shows up perfectly now.

[Deep Thought]

Yep, now it does, just not in the .txt.

Not sure, but I think it adds weird chars in if you copy-paste it from the Print Topic page.

[souvik1997]

Can you create programs and change their sizes later?

[Deep Thought]

There's are InsertMem/DeleteMem b_calls to do just that. You have to check for yourself if there's enough free RAM, though, and you also have to update the size bytes (the two-byte number stored just before the program data).

[Calcaholic]

I've got troubles with the length( function used on appvars.

For example, with the following code I get the output 14, allthoug it should be 5, I guess...

Code: Select All | Copy To Clipboard

1 2 3

GetCalc("appvTST",5)->P length({P})->B Disp B>Dec

I have experimented with this function some time now and always got very confusing results...

[squidgetx]

When you create an appvar, it isn't always filled with zeros. Also, you don't need the curly brackets; length(P) will do.

[Deep Thought]

When you create an appvar, it isn't always filled with zeros. Also, you don't need the curly brackets; length(P) will do.

Yep, in fact length({P}) does something different from what you want.

[Calcaholic]

I tried it without those brackets too, but in this case I always got the output 0...

And by the way, I used the ZEROS( function to fill the appvar, but left line this out in the example, because I thought it wouldn't matter for the size length.

[ACagliano]

The zeros function just adds zeros to the end of the program when Axe compiles. It has no effect on the actual executable.

Also, you must do

"appvTST"->Str0
GetCalc(Str0,5)->P
length(P)->B
Disp B>Dec

[squidgetx]

@Acagliano; Quigibo added support for inline data, so putting the string into the getcalc command is fine.

Calcaholic; the reason it would return 0 is because the length function does its work using 0 to signify the "end" byte of the data string. So if your appvar contained the values 1,2,3,4,5,0,7,8,9,10 then length() would return 5. Since you filled it with zeros beforehand, that's why it is giving a length of 0

[kindermoumoute]

3)... ?
good job.