Updated and reviewed April 2011
xcall MIAMEX, MX_SETENV, envdef {,status}
MX_SETENV is used to define environment variables for the current process, including the special case of TERM, for which see Comments, below. To set environment variables for the remote ATE client, see AG_GETENV.
Parameters
envdef (String) [in]
Contains a definition string of the form "name=value" specifying the name of the environment variable to be set (e.g. defined or modified) and its value. For example, "TERM=AM62CG", or "MYNAME=Jack"
status (signed numeric) [out]
If specified, will return one of the following:
|
Code |
Meaningt |
|
0 |
Success |
|
-1 |
General error |
|
-2 |
Overflow of memory set aside for environment variables. |
Comments
In general, setting an environment variable doesn't have any immediate side effect. Instead the value is simply stored, for the purposes of retrieving it later, either using MX_GETENV, or indirectly by referencing the variable name in some other expression context, as in the examples below:
xcall MIAMEX, MX_SETENV, "MYPATH=c:\vm\miame\jack", status
...
open #ch, "%MYPATH%\myfile.log", output
In the example above, we use the %envvar% syntax, which is recognized by Windows as well as by A-Shell, regardless of the platform, in nearly all contexts where a filespec may be used. If specifying an environment variable in a UNIX shell context, use the syntax $env, e.g. $MYPATH.
Environment variable definitions are available only to the current A-Shell prcess, and to those child processes launched by it (e.g. by HOSTEXor MX_SHELLEX). As an example of the former, under UNIX:
xcall MIAMEX, MX_SETENV, "MYPATH=/vm/miame/jack", status
...
xcall HOSTEX, "ls -l $MYPATH/a*", STDOUT$
A-Shell itself defines and recognizes several environment variables.
The TERM environment variable, used by UNIX—and A-Shell—to indicate the type of terminal in use, is a special case. When set from within an A-Shell session connected to a remote terminal (e.g. a TELNET or SSH session), A-Shell also re-initializes its terminal configuration and possibly changes its internal terminal "driver" to match the terminal type.
For A-Shell/UNIX, the TERM variable is typically established automatically when the TELNET/SSH session is initiated. But you may also set it manually prior to launching A-Shell (from the shell prompt), or you can set it via the -td command line switch.
Update Notes
Prior to 5.0, MX_SETENV used a different syntax:
xcall MIAMEX, MX_SETENV, envvar, value, status
Where envvar was the name of the variable to set and value was the value. This syntax is still supported for compatibility but is deprecated.