JAMS 7.x Help
Parsing Parameters and Variables

Parsing allows the values of Parameters and Variables to be used in various areas of JAMS such as a Job's source or in an Alert. This can be very useful for making your Jobs and other JAMS objects more dynamic. The syntax described below shows examples when  using Parsing.

To access the value of a Variable or Parameter use the format "<<ParameterName>>" or "<<VariableName>>". Parsing allows you to assign the values of Variables or Parameters to a variable within your source, or by directly using the values themselves. It is possible to use parsing to call Variables from other Folders.

Note: If a Variable and a Parameter have the same name the Parameter's value will be used.
Variable and Parameter Parsing
Copy Code
#
# As shown below you put the JAMS Variable or Parameter's name in quotes if you want to pass it in
# as a string. If the JAMS Variable or Parameter is an integer then you do not need to put it in quotes.
#
$myPath = "<<pathVariable>>"
$numberOfServers = <<numberOfServers>>

#
# You can use commands such as Get-ChildItem directly on a parsed Parameter or Variable.
#
if((Get-ChildItem "<<ParameterName>>" | measure-object | select-Object -ExpandProperty Count) -gt 0)
{
 Write-Host "files found"
}
else
{
 Write-Host "no files found"
}

Parsing allows for the use of standard .NET format strings. This provides better control how parsed values are formatted. One common example of this is using .NET DateTime string formatting in order to have Parameter or Variable values passed as a specific date/time format. To do this use the format: "<<VariableName("formatting here")>>" or "<<ParameterName("formatting here")>>".

Date Time String Formatting
Copy Code
Write-Host "The provided date is <<date1("MM/dd")>> in the year <<date1("yyyy")>>"

$birthday = "<<date("MM/dd/yyyy")>>"

It is also possible to maintain a Parameters type and value in a Job that contains a PowerShell source. This is done by using the format "param($ParameterName)" or "param($ParameterName1,$ParameterName2)" for multiple parameters. This must be done in the first line of the source and will inherit the type and value of the Parameter into a PowerShell variable named $ParameterName.

Note: This feature is only available for Parameters and will not work with JAMS Variables.
Using Param in PowerShell
Copy Code
param($DateParam)

#
# If you have a Parameter that is a DateTime type named "DateParam" the code above
# creates the PowerShell variable "$DateParam". $DateParam will inherit the type and
# value of the DateParam Parameter.
#
$Today = Get-Date
if($DateParam -lt $Today)
{
 Write-Host "This date occurred in the past."
}

In PowerShell it is possible to maintain data types of Variables such as DateTime and Boolean using casting as shown below. By defining the type of the Variable, PowerShell casts the value returned from parsing as the correct type instead of leaving it as a string. This is done by using the format: [dataType]$varName = "<<parsedValue>>".

Maintaining Data Types using Casting
Copy Code
#
# floatVariable is a float type Variable with the value "10.5". boolVariable is a Boolean type variable with
# the value "True". date1 is a DateTime type variable with the value "2/15/2012".
#

[Float]$exampleFloat = "<<floatVariable>>"
Write-Host "$($exampleFloat) | $($exampleFloat.getType())"
#returns: 10.5 | float
#
# In order to maintain the type of a Boolean property you need to use the
# format: [Bool]$testBool = $<<JAMS.PropertyName>> or
# [Bool]$testBool = $<<JAMS.Job.PropertyName>>. The $ is needed before the parsing
# because the parsed property is substituted with True or False and PowerShell
# is expecting $True or $False.
#
[Bool]$exampleBoolean = $<<boolVariable>>
Write-Host "$($exampleBoolean) | $($exampleBoolean.getType())"
#returns: True | bool
#
# Properties in JAMS that are DateTime can be returned in various formats, so
# in order to have a consistently working cast we need to
# specify the formatting as "O".
#
[DateTime]$exampleDate = "<<date1("O")>>"
Write-Host "$($exampleDate) | $($exampleDate.getType())"
#returns: 02/15/2012 00:00:00 | System.DateTime

Search Paths and Qualifying Variable Names

Defining a Search Path

Variables are first searched within the Folder the Job is located, as well as anything referenced in the Folder's search path. The search path is assigned at the Folder level and defines where items, such as Variables can be searched for. This is in addition to the Folder itself. Items such as Variables or Notification Jobs, with a location defined in the search path, are treated as if they are in the same Folder. For example, you could have a top level Folder, "Folder B" that contains a Variable "Variable1", and another top level Folder, "Folder A". If Folder A includes Folder B in its search path then Jobs located in Folder A can reference Variables in Folder A and Folder B with normal parsing syntax (<<Variable1>>). This can be very useful if you copy a Job from one Folder to another. This is because the Folder's search path can define where parsed values can come from. In the situation described above you can move the Job that references "Variable1" into Folder B and JAMS can still correctly parse the value for Variable 1. It is also possible to move the Job to another Folder, "Folder C" that also contains a variable, "Variable1". By relying on the Folder's search path the Job can dynamically find the correct variable to use for parsing.

To define a search path open the Properties tab of the Folder definition. Open the Source Options group and enter the desired Folder name into the Search Path field. You can enter multiple Folder names by separating each name with a comma, e.g.,  (\FolderName1, \FolderName2).

 

Qualifying Variable Names

An alternative to using a Folder's search path is to fully qualify the path to the Variable. This makes it possible for a Variable to be referenced from a specific Folder. This is done using the format: "<<FolderName\VariableName>>" and allows Variables in other Folders to be used just as easily as Variables in the same Folder the Job is located. This can be useful if you have a specific variable the Job needs to reference regardless of where the Job resides, thus allowing the reference to remain the same even if the Job is copied into another Folder. This is different than using a Folder's search path because the Job can specify exactly where a Variable should be found, and also allows a Variable with the same name to be called from multiple Folders as shown in the sample code below.

Qualifying Variable Names
Copy Code
Write-Host "A variable in another Folder: <<folder\samplesVariable>>"
Write-Host "The sampleVariable could be in another Folder as well: <<folder\sampleVariable>> versus <<Samples\sampleVariable>>"
Write-Host "The value of sampleVariable in the same Folder or search path as the Job: <<sampleVariable>>"
Note: For backwards compatibility if a Variable is not found in the Folder the Job is located, JAMS searches all other Folders for the Variable. If the Variable has a unique name then it will use the value it found regardless of which Folder it is in.

Click here for a downloadable sample.

See Also

 

 


Topic updated: 12/7/2017
©2019 HelpSystems, LLC. All Rights Reserved.

Send comments on this topic.