Signiant Support

Understanding Signiant variable substitution Print


Overview 

This article offers a short discussion on how to use Signiant variables are substituted when used in scripts within your custom solutions. 

Discussion

Signiant keywords and variables are accessed in scripts by using tokens following the %VariableName% syntax.
 
Examples:
my $userName = '%src_user%';
 
my $targetDirectory = '%TargetDirectory%'
 
if ( '%UseCompression%' eq 'yes' ) {
       print "Compression is turned on\n";
}


These Signiant variables are substutited before execution time by the agent software.  Where a Signiant variable is found, the agent will substitute the current value for that variable in the token's place.  Once all substitutions are done, the script is then given to the appropriate script interpreter (Perl in the above examples).  The script interpreter then executes the script with all substitutions in place.
 
The important thing to note is that the script intepreter has no knowledge of the Signiant variables at all.  By the time the agent hands the script to the intepreter, the tokens have been replaced with the actual text of the variable values.  Assuming that the value of %src_user% is 'bob', %TargetDirectory is '/usr/shared/data' and %UseCompression% is 'no' the actual code executed by Perl in the above examples would be:

my $userName = 'bob'; 
 
my $targetDirectory = '/usr/shared/data'
if ( 'no' eq 'yes' ) {
       print "Compression is turned on\n";
}


Since substitutions happen before the script is executed by its interpreter, it is possible that a variable's value could cause an error with the script.  For example, if %TargetDirectory% was defined as "/data/shared/Bob'sData", the actual code executed by the interpreter (Perl in this case) would be:

my $targetDirectory = '/data/shared/Bob'sData';

This would trigger a syntax error, as the single quote in "Bob'sData" closes the string.  However the unquoted text following the second single quote is unexpected, generating the error.
 
When designing your own custom solutions, these substitutions need to be kept in mind.  Where possible, modify your code to handle these common cases.  The TargetDirectory case above can be solved with the following:

my $targetDirectory = q|%TargetDirectory%|;

which would execute the code

my $targetDirectory = q|/data/shared/Bob'sData|;

In this particular case, the script is using Perl's 'q' command to specify the vertical bar "|" character to act as a single quote for this assignment.
 
Note that other substitution cases could produce other syntax errors. 
 
Another non-obvious consideration is that modifying a Signiant variable in a script does not change the value of that variable until the next script executed in the templates execution path.  Consider the following case where %UseCompression% is set to 'yes', but another condition can override this by assigning a value to $neverCompress:

if ( $neverCompress ) {
     print "%dds_set%UseCompression=no\n";

}
 
if ( '%UseCompression%' eq 'yes' ) {
     print "Using Compression\n";
}


After substitution, the code executed by the interpreter would be:

if ( $neverCompress ) {
     print "%dds_set%UseCompression=no\n";
}
 
if ( 'yes' eq 'yes' ) {
     print "Using Compression\n";
}


and the result would be that the "Using Compression" message would be printed in the log even if $neverCompress was true.  To handle these cases, it is best to assign the value of a Signiant variable to a variable used by your scripting language:

my $useCompression = '%UseCompression%';
if ( $neverCompress ) {
     $useCompression = 'no';
}
 
if ( $useCompression eq 'yes' ) {
     print "Using Compression\n";
}
print "%dds_set%UseCompression=$useCompression\n"';
 

Any scripting language will have similar behaviour.  Perl was used in the examples for this article as it is a common scripting environment available on all agent installations.