This is the first post in a 3-part series about Environment Variables in t scripts:
- Introduction to Environment Variables
- Accessing Environment Variables from CANlib
- Kvaser TRX and Environment Variables
Developer Blog
01/09/2015
by Magnus Carlsson
Introduction to Environment Variables (1 of 3)
This first post introduces the environment variables and shows how they can be used in a t program.
Environment variables are used to communicate between different t scripts or with a PC using CANlib. Figure 1 shows three scripts that are currently running on a Kvaser device. When Script 1 sets an environment variable, the new value will be available for reading in the other scripts, as well as from a PC using CANlib. In addition to this, a script may also declare a hook that is run whenever a specific environment variable value is set.
Figure 1: An overview of how the information about the environment variable’s value is distributed.
The term “envvar” is often used as a shorthand writing for the longer environment variable. For full documentation, read the Kvaser t Programming Language documentation 1.
An environment variable can only be defined in an envvar section in a t program. Just like a variable defined in a variables section, an environment variable is visible globally. This is equivalent to defining something in global scope in a C program, i.e. the variable is visible between the declaration and the end of the compilation.
The type of an environment variable can be either int, float or an array of char.
envvar {
char Message[128];
int Severity;
int HostIdRequest;
int HostIdConnected;
}The size of an environment variable is limited to ENVVAR_MAX_SIZE (4096 in version 3.2 of the t compiler) and you can define up to a maximum of 32 environment variables.
Unlike ordinary variables, environment variables cannot be initialized or accessed directly in the t program. Instead, they are accessed using envvarSetValue() and envvarGetValue().
void setHostIdConnected (int value)
{
hostIdConnected = value;
envvarSetValue(HostIdConnected, value);
}The function envvarSetValue() will set the value of the environment variable. The actual update will be queued and therefore delayed until the execution of the current hook has finished. A notification that the environment variable has been updated is then propagated to all programs that have declared the same environment variable and have a corresponding on envvar hook. In this context, updated includes the setting of the same value as before.
Since the actual update of the environment variable is delayed, it is possible to initiate a new update of the same environment variable during this delay. In this case, the older value is lost. So every time you read an environment variable you get its latest value and if you want to make sure that every change is seen, you need to implement a hand shaking scheme using at least two environment variables.
// Print incoming messages
on envvar Message {
char msg[128];
int severity;
envvarGetValue(Message, msg);
envvarGetValue(Severity, &severity);
printf("Severity: %d - %s\n", severity, msg);
}The function envvarGetValue() retrieves the last known value of the environment variable. The result is undefined if the environment variable is not initialized. Full program listings are available on http://github.com/Kvaser/developer-blog.
The next post in this series will show how to access the environment variable in CANlib.
Footnotes:
1 The Kvaser t Programming Language documentation is available from https://www.kvaser.com/download/#?filter=t%20programming.
