prgmAVLIB

TI-83+/84+ Application Variable Library

prgmAVLIB is an Axe program for TI-83+/84+ series graphing calculators that allows TI-BASIC programs to manipulate application variables via TI-OS string variables.  It is written in Axe 0.4.4 and no shell or other executable is required to use it.  It is open-source software released under the X11 License.

Dependencies:  None
Inputs:  Str1, Ans
Changes:  Str2 (only when reading application variables), Ans
Reads, writes, archives, unarchives, and deletes user-specified application variables of arbitrary names, lengths, and content.

Usage:

  1. Str1 should contain a string of the format "NAME=VALUE".

    NAME:

    • NAME is the name of an application variable.
    • The name MUST be between one to eight characters long, inclusive.
    • Uppercase, lowercase, and numeric tokens, as well as spaces, hyphens (the minus sign, not the negative sign), and periods will work properly.  Other characters will probably not look right in the Memory menu.
    • Variables whose names do not begin with an uppercase or lowercase letter will NOT show up in the Memory menu.
    • The first byte (0xBB) of two-byte tokens other than lowercase ones (which are converted into ASCII) is ignored.
    • The name MUST NOT contain an equal sign because this is used to split the name and value.

    VALUE:

    • VALUE is what you want to store in the application variable.
    • It is only required for operation 1 (write).
    • It is ignored, and may be omitted, for all operations except operation 1.
    • The value MAY contain equal signs, and it is not converted like the name is.

  2. Ans should contain an integer from 0 to 5, inclusive.  This number MUST be one of:

    0:  Read the application variable NAME.  Variable contents are written to Str2.  If the application variable is archived, then it is NOT unarchived.
    1:  Write VALUE to the application variable NAME.  VALUE MUST be specified.  If the application variable already exists, it is overwritten, even if it is archived.  If it is archived, then the new variable will NOT be archived.
    2:  Archive the application variable NAME.
    3:  Unarchive the application variable NAME.
    4:  Delete the application variable NAME.
    5:  This operation checks to see if the application variable NAME exists.  Ans will contain 0 if it does, 3 if it does not, or another integer if there was another error.  See the Output section for all possible values of Ans.

    All operations should work properly whether or not the application variable is archived.

  3. Run prgmAVLIB.
  4. Check Ans.  If it is 0, then the operation was successful; otherwise there was an error.  See the Output section for a list of possible values and their meanings.
  5. For operation 0, Str2 will contain the contents of the specified application variable.  See the Output section for details.

Make sure that the contents of Ans is a valid operation.  The case of a large or non-integer value being in Ans when you run this program has NOT been tested, so you may get a RAM clear if Ans contains a large or non-integer value when you run this program.

Note:  When you run this program, the cursor might be moved back to the top-left of the screen.  This is known to happen when CalcUtil is activated, for example.  You should compensate for this in any program you plan on distributing if it uses prgmAVLIB.

Example:

This is an example of prgmAVLIB being used from the TI-OS home screen.  Empty lines are added for clarity.

"AppVar=SPAM SPAM SPAM SPAM"->Str1 1:Asm(prgmAVLIB Done Ans 0 2:Asm(prgmAVLIB Done Ans 0 0:Asm(prgmAVLIB Done Ans 0 Str2 SPAM SPAM SPAM SPAM

This will write "SPAM SPAM SPAM SPAM" to the application variable AppVar, archive it, copy the same variable's contents (without unarchiving it) to Str2, and finally display Str2.

You should always check Ans to make sure the operation was successful; otherwise you might have problems if you try to do anything with the output or the application variable later.

Output:

If the operation is 0, then Str2 will contain the variable contents.  Str2 will be created if it does not exist, and it will be overwritten otherwise.

Ans will always contain an exit code (unless a TI-OS memory error is raised), which will be one of:

0:  Success.
1:  Could not open Str1.
2:  Input error (bad operation, Str1 is not formatted correctly, the name is too long, etc.).
3:  Could not open the specified application variable, or the variable doesn't exist.
4:  Could not create Str2 when reading the specified application variable.
5:  Could not (un)archive the specified application variable.

Application variable format:

Application variables made by this program have the same format as TI-OS string variables.

Changing the input and output strings:

To change which TI-OS strings are used for input and output, edit the source code (prgmAVLIBSRC) by changing these lines and compiling it using Axe:

.In/out Strs "Str1"->Str1 "Str2"->Str2

For example, to use Str9 for input and Str0 for output, change these lines to

.In/out Strs "Str9"->Str1 "Str0"->Str2

and compile.

Especially if you plan on distributing the new executable, you should also change the first line (.AVLIB) so that the name of the compiled program (the part after the dot) does not conflict with other copies that the user may have installed.

prgmAVLIB should be compiled with Shell set to No Shell in the Axe Parser.

You are allowed to redistribute the modified executable and/or source code under the terms of the X11 License.  See the License section for details.

License:

Copyright (c) 2010 Scott Zeid. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name(s) of the above copyright holders shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.

This is the X11 License.  It means that you are allowed to modify this program and redistribute it and/or its source code, modified or not, under the terms of this license.  Namely, you must reproduce the copyright and permission notices, and you MUST NOT use my name in advertising or any other promotion, or as an endorsement, without getting written permission, from me, BEFORE doing so.

Also, NO WARRANTY IS PROVIDED, and I am NOT liable for ANY problems or damages, including but not limited to RAM clears, archive clears, data loss or corruption, property damage, any illnesses, injuries, or deaths resulting from the use of this program (or anything based on it) or any legal or disciplinary actions taken against you.  This also means that this program is not guaranteed be stable or to work properly, or even at all, even though I have tested it thoroughly, and I personally believe that it works and that it is stable.

This license is believed to be compatible with the GNU General Public License.

Contact information:

The author, Scott Zeid, may be contacted regarding this program at ticalc AT srwz DOT us.