Variables

  • Variables have a lifecycle and a scope: the lifecycle of a variable is always confined to the web page where they have been declared. The scope can be public, private or local. By default all variables of a page are public.
  • Each web page is a program of its own and has its own variables that are lost once the page it's been displayed to user.
  • Variables can be passed from a page to another only by means of HTML structures as web form fields or URL parameters.
  • Variables can also be exported into memory files (a.k.a. as sessions) for preserving their values and then retrieve them in another page.
  • Variables passed from a page to another using the standard method are called webVars and have no lifecycle: they can survive as long as they are relayed from page to page.
  • WebVars are the main method to communicate between pages

How do you create a variable?

Well, it's not that difficult:

private nnn
local rrr
public vvv
That's it. But wat do 'private' and 'public' mean?

The scope of a variable

All variables start their life at the exact point of the web page where they are declared. Variables can be of public, private or local scope

  • variables explicitly declared are considered as public
  • variable implicitly declared by assigment are considered private
  • to be considered local, variables must be explicitly declared local

Public variable

Is visible to every function, outside and inside a page. If a function changes the value of a pulic variables passed to it (or referenced elsewhere) during its execution the new value takes place and old value is overwritten permanently.

Private variables

These are also visible to every function in the page, exactly like publics, but their original value is somehow protected. Values of private variables can be changed only by the code of the function where they are declared. If they are declared outside a function (typically at the top of the page) the value assumed originally can not be changed by external or internal functions.

Local variables

These variables live and die inside functions. If a variable is declared local it is visible only inside the function where it is declared, even if in the same page or in other functions other variables with the same name already exists.

So it is advisable to always declare your variables Local in functions. You won't get any conflicts with other variables when you use the function in other pages that may contain a variable with the same name. When your applications grow bigger and you want to re-use code, this is important.

Special DBFree variables

Alright now this is an important part. Because these variables can do a lot of work for you. And that's what a good framework is all about!

DBFree operates only on web pages: this goes beyond the traditional use of MaxScript (that was born to be used BOTH for desktop applications AND for webpages) thus the following variable types are made available only by the implementation of MaxScript offered by DBFree and only for web applications.

Standard WebVars (Web Variables)

These variables live and die on the server and only while it assembles the web page. They are passed to a user's browser along the page using the HTTP protocol. The webVars names below are reserved:

VA var cAction Current action code (webObjects)
VO var cOption Current option code (webObjects)
VK var cKey A generic key value (text)
VKF var cKeyField Key field for queries
VKV var cKeyValue key value for queries
VAL var cAlias DB alias for queries
VMT var cMaster master table for relations
VMTX var cMasterNdx index to use for master table
VST var cSlave slave table for relations
VSTX var cSlaveNdx index to use for slave table
VR var nRecNo Arbitrary record number
VRM var nRecMaster Record number to go for master table
VRS var nRecSlave Current record in the slave table

Note: WebVars are always of CHAR type (plain text) and each one can store as much text as the server is set for (usually a maximum of 1KB).

Standard Global Vars

Stored permanently server-side and visible to any user.

_WEBROOT webroot()
_SITEID getenv("SERVER_NAME")
_PRODUCT mspconfigvar("PRODUCT")
_MSPDIR mspconfigvar("MSPDIR")
_LIBDIR mspconfigvar("LIBDIR")
_MEMDIR mspconfigvar("MEMDIR")
_DATADIR _MSPDIR +"\db\"
_DOWNDIR _MSPDIR +"\public\out\"
_UPDIR _MSPDIR +"\public\in\
_WEBID var myWebId
_DBTYPE (empty)
_CARGO Available

Session Vars

Stored permanently server-side and visible only inside pages that use the same session seed. Every user has a his/her own set of values.

Variable Initial value Note
xcGlobMem var _globals Used for cross checks
xcAppId var xcAppId If not declared defaults to var myWebId
xcWebId (empty) Depending by the type o app can be empty ir get an arbitrary value
xcDevId (empty) Will store the device ID
xcDevType (empty) Will store the device type
xcRoot webroot() Can be changed to store APP's own root if needed
xcUsr (empty) Reserved
xcUsrName (empty) Available
xcUsrID (empty) Available
xcUsrGrp (empty) Available
xcUsrIp ip() Reserved: it stores the user's IP address
xcUsrLev 0 Available for storing the minimum role level for accessing APPS
xcSeed var cSeed Reserved
xjSeed (empty) Reserved
xcSessMem (empty) Reserved
xlAuth (empty) Available for storing a logical value representing authorization for access
xcDateTime (empty) Available
xcDownDir (empty) Available for storing the physical path for downloads (outgoimg files)
xcDownAlias (empty) Available for the alias (server side) pointing to download folder
xcUpDir (empty) Available for storing the physical path for uploads (incoming files)
xcUpALias (empty) Available for the alias (server side) pointing to upload folder
xcDbType (empty) Available for soting the current default driver
xcDbDir (empty) Available for storing the path to current database
xcHome (empty) Available for storing a backlink to home page
xcBack (empty) Available for storing an arbitraty backlink
xcDateTime (empty) Available
xcCargoMem (empty) Reserved (is the name of session secondary file)
xcCargo (empty) Available for storing text (max 4095 bytes)
xnCargo (empty) Available for storing a number
xlCargo (empty) Available for storing a single logical value
xdCargo (empty) Available for storing a single calendar date
xdLogDate (empty) Available for storing the date when user has logged in last time
xcCurrDb (empty) Available for storing the name of the table actually in use
xcLogTime (empty) Available for storing the time string when user has logged in last time

Local Storage (browser) jVars

Stored permanently client-side: visible to any user when connecting from a browser that carries them.

Variable Initial value
jSeed Set by jdetect()
jUsr Set by initJvars()
jUsrId Set by initJvars()
jUsrName Set by initJvars()
jAgent Set by jdetect()
jWW Set by jdetect()
jHH Set by jdetect()
jAvWW Set by jdetect()
jAvHH Set by jdetect()
jCargo Empty: Available for storing arbitrary values (up to 5MB)