Magsbot Help

Lists in Magsbot

Magsbot makes extensive use of lists of several kinds, which probably leads to some confusion. On this page I'll detail those different types of lists.

Internal lists

Internally, the Magsbot program uses the TList Delphi class a lot, and occasionally I'll refer to this list or that list in the program when explaining how queueing or event handling works, but generally you don't need to be concerned with these except to understand what I'm referring to if I say something about lists "internal to Magsbot."

Global variable list

The global variable list is what you see when you press Ctrl-F3 in Magsbot. These variables are available to you anywhere in the scripts you write, and are automatically saved in the varlist.var file when you exit Magsbot, and reloaded when you start Magsbot. In a script, you can create or assign a global variable either using the GLOBAL or GLOBALSTR commands (for a numeric or string variable, respectively), or by using the short form of assignment like @@x=12 or $$z="some text of mine" (note that this differs from the short form of assignment used for local variables, which would be like @x=12 or $z="some text of mine"). When you use the GLOBAL or GLOBALSTR commands, the variable name can have any characters in it (for example, GLOBAL "this is a variable name!! wow!"=12); but with the short form of assignment, the variable name must contain only letters, numbers or the underscore, and begin with a letter.

You can retrieve the value of a global variable by directly using the name (e.g. @x or $z), but if a local variable (see below) has the same name, then the local variable will override the global. If you want to make sure you are getting the value from the global variable, then you can use the @gv_ or $gv_ functions, like @gv_[x] instead of @x or $gv_[z] instead of $z.

You can free a global variable using the FREEVAR or FREEVARS commands.

Numbered lists

Numbered lists, sometimes called just "lists" elsewhere in the Magsbot documentation, are the first kind of lists that were available for use in scripts, and were not originally built-in to the program, but were implemented entirely using macros. They proved to be so useful however that I later added some built-in commands and functions to deal with them.

Numbered lists are actually just groups of global variables with a similar name, specifically, with a prefix and an item number separated by a colon. For example, $somelist:3 or @mylist:12. Note that I refer to the number as an "item number" and not an "index", because the number doesn't necessarily refer to the variable's position in the list. If you create a numbered list with three items like @mylist:1, @mylist:2 and @mylist:3, then delete @mylist:2, then @mylist:3 will become the second variable in the list; the item numbers are not updated to reflect its new position.

You can assign a value to a numbered list using ENLIST, ENLIST_, SETITEM or SETITEM_ (for example, ENLIST_ mylist 12 or SETITEM_ mylist 1 12 or ENLIST somelist "a string" or SETITEM somelist 1 "a string"). Or, you could assign it directly as a global using GLOBAL or GLOBALSTR. That is, GLOBAL "mylist:2"=7 has the same effect as SETITEM mylist 2 7.

You can retrieve a value from a numbered list using the @listitem, @litem, $listitem or $litem functions. You could also retrieve a value directly using @gv_ or $gv_, for example @gv_["mylist:2"] is the same as @litem[mylist,2].

Items can be freed from a numbered list using FREEITEM or FREEITEM_. Or you could use FREEVAR, for example FREEITEM_ mylist 2 is the same as FREEVAR "@mylist:2". An entire list can be freed using FREELIST or FREELIST_, or by using FREEVARS. FREELIST_ mylist is the same as FREEVARS "@mylist:".

There are many other functions for manipulating numbered lists, which you can see here.

Object lists

Object lists are one kind of numbered list, used to store survey information. The item number of each item in the list is the object number from the survey, and the value of the list item is a comma-delimited sequence of the survey data (location, model, description, etc.). Object lists are created during a survey, formerly by code in the standard behavior table, but in Magsbot 6.0 the ability was added to send survey information directly to an object list (or a vlist, see below) without passing through the behavior table. The old method was invoked using the various survey buttons on the Survey tab of the Actions panel, but the new faster method is used by performing a survey from the survey dialog (F9).

See here for more details about object lists.

Position lists

A position list is a numbered list that stores position information used for bots that patrol or perform random movement.

Local variable lists

Local variable lists are similar to the global variable list, except they are temporary and exist only in the context of a single event or action button click. A new local variable list is created automatically for each event that is sent to the behavior table, and destroyed after the table has finished processing the event. (Note that local variables assigned in an action that was triggered by an event, are therefore passed on to subsequent rows of the table and are available in any other actions triggered by the same event.) Assignment to local variables is almost always done using the short form (@x=12 or $z="my string") but can also be done using the ASN or ASNS commands. (ASN x=12 is the same as @x=12.)

Local variables can be retrieved directly (@x) or using the @var or @v_ functions. See here.

When an action button is called using the CLICKBTN command, the local variable list is passed to the button and any variables in the list can be used or changed within the button code. The local variable list is also passed back out again, with any changes it contains. However when a button is called using the FTN or FTN_ commands or @ftn or $ftn functions, a new local variable list is created and only the values given as arguments are passed in. Within the button code, the ARGS command is used to assign names to the argument values. Only variables listed in the RETURNS command within the button code will be passed out, except when the button is called using @ftn or $ftn, and then the function return value (assigned within the button code using RETURN or RETURN_) will also be passed out.

VLists ("user-created lists")

Vlists are another form of variable list, similar to the global or local variable lists, but entirely separate. Variables within a vlist are therefore only accessible using the vlist handle with the @lvar, @lv_, $lvar or $lv_ functions. A vlist is created within a script using the @vlist function, which returns the handle to the vlist. Items are stored in a vlist using the STORE and STORE_ commands. Items in a vlist can be freed using FREELVAR or FREELVARS and the entire list can be freed using FREEVLIST.

See vlist related commands here, and vlist related functions here.