Author Topic: External Vars Tutorial  (Read 21539 times)

0 Members and 1 Guest are viewing this topic.

Offline FinaleTI

  • Believe in the pony that believes in you!
  • CoT Emeritus
  • LV10 31337 u53r (Next: 2000)
  • *
  • Posts: 1830
  • Rating: +121/-2
  • Believe in the pony that believes in you!
    • View Profile
    • dmuckerman.tumblr.com
External Vars Tutorial
« on: December 12, 2010, 11:25:22 am »

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 (Y0-Y9).

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

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.

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",Y0)
GetCalc("appvAPPVAR2",Y0)


This would copy the appvar APPVAR to file Y0, then copy the appvar APPVAR2 to file Y0. Accessing file Y0 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",L1+1,2)
0->{L1+3}
E15->{L1}
GetCalc(L1)->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",L1+1,2)
This line copies the name of the variable (in this case, "HI") to L1+1.

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

E15->{L1}
This line stores the type byte of the variable to L1. 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(L1)->A
This uses the string you just constructed at the beginning of L1 to create the variable.


« Last Edit: July 17, 2011, 02:16:38 pm by FinaleTI »


Spoiler For Projects:

My projects haven't been worked on in a while, so they're all on hiatus for the time being. I do hope to eventually return to them in some form or another...

Spoiler For Pokemon TI:
Axe port of Pokemon Red/Blue to the 83+/84+ family. On hold.

Spoiler For Nostalgia:
My big personal project, an original RPG about dimensional travel and a few heroes tasked with saving the world.
Coding-wise, on hold, but I am re-working the story.

Spoiler For Finale's Super Insane Tunnel Pack of Doom:
I will be combining Blur and Collision Course into a single gamepack. On hold.

Spoiler For Nostalgia Origins: Sky's Story:
Prequel to Nostalgia. On hold, especially while the story is re-worked.

Offline Deep Toaster

  • So much to do, so much time, so little motivation
  • Administrator
  • LV13 Extreme Addict (Next: 9001)
  • *************
  • Posts: 8217
  • Rating: +758/-15
    • View Profile
    • ClrHome
Re: External Vars Tutorial
« Reply #1 on: December 12, 2010, 11:36:36 am »
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 ???




Offline Michael_Lee

  • LV9 Veteran (Next: 1337)
  • *********
  • Posts: 1019
  • Rating: +124/-9
    • View Profile
Re: External Vars Tutorial
« Reply #2 on: December 12, 2010, 11:58:04 am »
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?
My website: Currently boring.

Projects:
Axe Interpreter
   > Core: Done
   > Memory: Need write code to add constants.
   > Graphics: Rewritten.  Needs to integrate sprites with constants.
   > IO: GetKey done.  Need to add mostly homescreen IO stuff.
Croquette:
   > Stomping bugs
   > Internet version: On hold until I can make my website less boring/broken.

Offline FinaleTI

  • Believe in the pony that believes in you!
  • CoT Emeritus
  • LV10 31337 u53r (Next: 2000)
  • *
  • Posts: 1830
  • Rating: +121/-2
  • Believe in the pony that believes in you!
    • View Profile
    • dmuckerman.tumblr.com
Re: External Vars Tutorial
« Reply #3 on: December 12, 2010, 12:01:25 pm »
Does it show up properly now?

1) Appvars and Programs
Spoiler For Spoiler:
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]
GetCalc("appvAPPVAR")→PointerWhere '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]
GetCalc("appvAPPVAR")→AThis 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]
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]
GetCalc("appvAPPVAR",Size)→PointerWhere 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]
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]
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]
GetCalc("appvAPPVAR",File)Where File is the token for a Y-Var (Y0-Y9).
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]
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]
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]
GetCalc("appvAPPVAR",Y0)
GetCalc("appvAPPVAR2",Y0)
This would copy the appvar APPVAR to file Y0, then copy the appvar APPVAR2 to file Y0. Accessing file Y0 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 Spoiler:
Accessing real vars is fairly easy to do, actually.
First, getting the pointer to a real var is:
Code: [Select]
GetCalc("varA")→PointerWhere 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]
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]
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).


Spoiler For Projects:

My projects haven't been worked on in a while, so they're all on hiatus for the time being. I do hope to eventually return to them in some form or another...

Spoiler For Pokemon TI:
Axe port of Pokemon Red/Blue to the 83+/84+ family. On hold.

Spoiler For Nostalgia:
My big personal project, an original RPG about dimensional travel and a few heroes tasked with saving the world.
Coding-wise, on hold, but I am re-working the story.

Spoiler For Finale's Super Insane Tunnel Pack of Doom:
I will be combining Blur and Collision Course into a single gamepack. On hold.

Spoiler For Nostalgia Origins: Sky's Story:
Prequel to Nostalgia. On hold, especially while the story is re-worked.

Offline Michael_Lee

  • LV9 Veteran (Next: 1337)
  • *********
  • Posts: 1019
  • Rating: +124/-9
    • View Profile
Re: External Vars Tutorial
« Reply #4 on: December 12, 2010, 12:04:56 pm »
Yup.  It shows up perfectly now.
My website: Currently boring.

Projects:
Axe Interpreter
   > Core: Done
   > Memory: Need write code to add constants.
   > Graphics: Rewritten.  Needs to integrate sprites with constants.
   > IO: GetKey done.  Need to add mostly homescreen IO stuff.
Croquette:
   > Stomping bugs
   > Internet version: On hold until I can make my website less boring/broken.

Offline Deep Toaster

  • So much to do, so much time, so little motivation
  • Administrator
  • LV13 Extreme Addict (Next: 9001)
  • *************
  • Posts: 8217
  • Rating: +758/-15
    • View Profile
    • ClrHome
Re: External Vars Tutorial
« Reply #5 on: December 12, 2010, 12:05:17 pm »
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

  • Guest
Re: External Vars Tutorial
« Reply #6 on: December 12, 2010, 01:23:05 pm »
Can you create programs and change their sizes later?

Offline Deep Toaster

  • So much to do, so much time, so little motivation
  • Administrator
  • LV13 Extreme Addict (Next: 9001)
  • *************
  • Posts: 8217
  • Rating: +758/-15
    • View Profile
    • ClrHome
Re: External Vars Tutorial
« Reply #7 on: December 12, 2010, 01:28:51 pm »
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).




Offline Calcaholic

  • LV1 Newcomer (Next: 20)
  • *
  • Posts: 13
  • Rating: +2/-0
    • View Profile
Re: External Vars Tutorial
« Reply #8 on: February 04, 2011, 05:39:02 am »
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]
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...

Offline squidgetx

  • Food.
  • CoT Emeritus
  • LV10 31337 u53r (Next: 2000)
  • *
  • Posts: 1881
  • Rating: +503/-17
  • rawr.
    • View Profile
Re: External Vars Tutorial
« Reply #9 on: February 04, 2011, 07:18:08 am »
When you create an appvar, it isn't always filled with zeros. Also, you don't need the curly brackets; length(P) will do.
« Last Edit: February 04, 2011, 07:18:18 am by squidgetx »

Offline Deep Toaster

  • So much to do, so much time, so little motivation
  • Administrator
  • LV13 Extreme Addict (Next: 9001)
  • *************
  • Posts: 8217
  • Rating: +758/-15
    • View Profile
    • ClrHome
Re: External Vars Tutorial
« Reply #10 on: February 04, 2011, 09:11:15 am »
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.




Offline Calcaholic

  • LV1 Newcomer (Next: 20)
  • *
  • Posts: 13
  • Rating: +2/-0
    • View Profile
Re: External Vars Tutorial
« Reply #11 on: February 04, 2011, 11:06:12 am »
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.

Offline ACagliano

  • LV8 Addict (Next: 1000)
  • ********
  • Posts: 919
  • Rating: +32/-2
    • View Profile
    • ClrHome Productions
Re: External Vars Tutorial
« Reply #12 on: February 04, 2011, 11:24:12 am »
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
« Last Edit: February 04, 2011, 11:25:35 am by ACagliano »

Offline squidgetx

  • Food.
  • CoT Emeritus
  • LV10 31337 u53r (Next: 2000)
  • *
  • Posts: 1881
  • Rating: +503/-17
  • rawr.
    • View Profile
Re: External Vars Tutorial
« Reply #13 on: February 04, 2011, 11:42:30 am »
@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

Offline kindermoumoute

  • LV8 Addict (Next: 1000)
  • ********
  • Posts: 836
  • Rating: +54/-3
    • View Profile
Re: External Vars Tutorial
« Reply #14 on: February 04, 2011, 12:40:00 pm »
3)... ?
good job. ;)
Projects :

Worms armageddon z80 :
- smoothscrolling Pixelmapping : 100%
- Map editor : 80%
- Game System : 0%

Tutoriel français sur l'Axe Parser
- 1ère partie : en ligne.
- 2ème partie : en ligne.
- 3ème partie : en ligne.
- 4ème partie : 10%
- Annexe : 100%