Allocator Procedures

In this section, the procedures that may be used in the Allocator configuration file are described.

LA::AddLicenseMonitor

Description
Use this procedure to declare which Monitor system Allocator talks to. This procedure may be called multiple times if there are multiple Monitor systems that need to be connected to Allocator.
Note: Although -nickname is an optional parameter if only a single Monitor is declared using this command, it must be specified with a unique nickname if multiple Monitor are declared through multiple AddLicenseMonitor commands.
Note: Current version of Allocator only supports connection to one Monitor instance. Support for multiple Monitor instances will be added in a future release.
Usage
LA::AddLicenseMonitor <host:port> [OPTIONS]
Required Arguments
<host:port> [host2:port2] ...
The first argument is a list of host:port elements (normally a list of just one). Alternately, the keyword "auto" can be used in place of the host:port specification, to detect the host and port automatically from the registry for the Monitor project name specified using -project.
Options
-project PROJECTNAME
Specify the name of the Monitor project. The default value is "licmon".
-access [normal|vtk]
This option is deprecated. The only available access is now vtk.
-version VERSION
Specify the version of the Altair Accelerator used to communicate with the remote Monitor system. The default value for this option is the latest 2016.09 version.
-local-file FILENAME
This is used only for debugging. Please do not use.
-nickname NICKNAME
Specify a short nickname to refer to this Monitor instance.
Note: If the config.tcl file contains multiple AddLicenseMonitor commands, each Monitor declaration MUST include a unique nickname.
-ssl [0|1]
Specify whether to use SSL to connect to this Monitor instance or not. This depends on whether this Monitor instance is running with SSL enabled or is running wth SSL disabled.
Examples
LA::AddLicenseMonitor bear:5555
LA::AddLicenseMonitor "bear:5555 calicmon:5555"
LA::AddLicenseMonitor bnglic:5555 -version 2016.03 -nickname BL
LA::AddLicenseMonitor lnx123:7755 -version SAME -project licmon_us -ssl 1

LA::AddResource

Description
Declare a shared resource.
Usage
LA::AddResource <RESOURCE_NAME> <TYPE> <MAP> [OPTIONS]
Required Arguments
<RESOURCE_NAME>
Name of the resource to be shared.
<TYPE>
Either an integer representing the total number of units to be shared, or string of the form "FlexLM/tag/feature", where tag/feature is the name of a FlexNet Publisher feature, inclusive of tag. These names are the ones used by Monitor. The "FlexLM" part of the type is case-insensitive.
<MAP>
A resource expression to which the resources is to be mapped.
Options
-expr <EXPRESSION>
EXPRESSION is an integer expression where the token '$N' represents the number total number of tokens as determined by TYPE. An example of this option is shown below.
-slowdown <RATIO>
This number is used to slow down the transfer of tokens to a queue that needs them. Specifically, if A is the number of allocated tokens now and T is the target number of tokens, and R is the "slow down ratio" set by this option, then the actual number of tokens transfered to the queue in each cycle of Allocator is ceil((T-A)*R). The default value of R is 0.5 while the valid range is from 0.1 to 1.0. This option is not supported in this release.
-tags <LIST_OF_TAGS>
LIST_OF_TAGS is a list of the tags that have licenses managed by Allocator. This option is necessary if you have a mixture of wannable and non-wannable licenses.
-debug <LEVEL>
Enable or disable debugging on this resource and set the debug level. A level of 0 disables debugging, and any positive integer enables it.
-overbook [0|1]
Enable or disable overbooking on this resource. A level of 0 disables overbooking, and 1 enables it.
Note: Enabling overbooking will automatically disable handle/job matching.
-match [0|1]
Enable or disable handle/job matching on this resource. A level of 0 disables matching, and 1 enables it.
Note: Matching can only be enabled if overbooking is disabled. Enabling overbooking will automatically disable matching.
Examples
# 10 tokens to be shared.
LA::AddResource MyTokens   10          ""
# Wan:licx is derived from the FlexNet Publisher feature called 'licx'
LA::AddResource Wan:licx   FLEXLM/licx "" -overbook 1;

LA::DefineResourceGroup

Description
If you have the same feature serviced by different FlexNet Publisher daemons, it may be advantageous to use this command to keep the various sources separated and allows Allocator to manage them as a group. This command is also recommended if you are using VOV_LM_VARNAMES to automatically set the value of the LM_LICENSE_FILE variable.
Usage:
LA::DefineResourceGroup <GROUP_NAME> <LIST_OF_ADD_RESOURCE_CALLS>
Required Arguments
<GROUP_NAME>
Name of the resource group.
<SCRIPTS THAT CALLS LA::AddResource>
Normally the script is a simple sequence of LA::AddResource calls (see examples below).
Examples
In this example, assume there are 3 sources for the license "hsim": US, CA, EU. Each source provides 10 tokens, for a total of 30 tokens. If you simply tell Allocator to manage the 3 sources, and if there is contention for the resource, then Allocator will try to balance each of the 3 sources.
# Wrong way to deal with multiple sources
LA::AddResource WAN_US:hsim FLEXLM/US/hsim ""
LA::AddResource WAN_CA:hsim FLEXLM/CA/hsim ""
LA::AddResource WAN_EU:hsim FLEXLM/EU/hsim ""
Instead, if you use a "resource group", then Allocator will try to balance the total number of tokens for the three sources, thus allowing each individual source to be allocated independently of the other two.
# Correct way to deal with multiple sources
LA::DefineResourceGroup WAN:hsim {
    LA::AddResource WAN_US:hsim FLEXLM/US/hsim ""
    LA::AddResource WAN_CA:hsim FLEXLM/CA/hsim ""
    LA::AddResource WAN_EU:hsim FLEXLM/EU/hsim ""
}

LA::AddAllResources

Description
If you have many WANable resources, it may be convenient to declare them all at once with this command. This procedure queries all Monitor systems for all features in selected tags and declares all Monitor systems as resources to be managed by Allocator.
Usage
LA::AddAllResources [OPTIONS]
Options
-resmapType <TYPE>
Specify the type to be used for the resourcemaps. For example, if the resmap type is "XXX" then the Allocator resources will be called XXX:featureName. The default value for -resmapType is "LicenseWAN".
-useGroups <BOOLEAN>
If -useGroup is true, then the features in different tags are grouped together with LA::DefineResourceGroup otherwise the available tokens are all aggregated together and the resource is managed as one.
-excludeTag <RX>
Used to exclude tags that are not supposed to be managed by Allocator. The option may be repeated.
-includeTag <RX>
Used to include tags that are supposed to be managed by Allocator. The option may be repeated.
Important: The -includeTag option is processed before the -excludeTag option. If the option is not specified, all tags are included, else only the mentioned tags are included. If a tag is both "included" and "excluded", then the exclusion rule prevails.
-orderTags <TAGLIST>
Define a partial order of tags. The option may be repeated.
Examples
# Exclude a specific tag called SNPS.  Remember that all strings are Regular expressions
LA:AddAllResources -excludeTag {^SNPS$} 

# Only add resources that have tag matching "_wan"; 

# All remaining resources will have type LicenseWAN

LA:AddAllResources -includeTag _wan -resmapType "LicenseWAN"

# Only add resources that have tag matching "_wan",
# but use LA::DefineResourceGroups for a finer management of the
# resources.
LA::AddAllResources -useGroups 1 -includeTag _wan -resmapType "LicenseGRP"

LA::AddSite

Description:
Define a queue, such as an Accelerator site, managed by Allocator.
Usage:
LA::AddSite <QUEUE@HOST> <NICKNAME> [{LIST_OF_WEIGHTS}] [OPTIONS]
Required Arguments
<SITE@HOST>
Specify the site@host name. This is easy for an Accelerator site. For LSF, you may want to pick an arbitrary name for SITE and choose the master host for HOST. Alternately, the @host may be omitted if using the -autodetect option.
<NICKNAME>
Specify a site nickname. This is a short name used in the browser interface and also used in other API calls. Make it short with no spaces.
Options
{LIST_OF_WEIGHTS}
An optional Tcl list of resource, weight pairs. The weights are used to decide the allocation of the resources in case of contention. We currently recommend to leave this empty and to use LA::SetResourceWeight instead.
-la [0|1]
Used by the parent Allocator in a hierarchical Allocator setup to define a child LA (using the -la 1 option).
Examples:
LA::AddSite child_la@jupiter CHILDLA {} -port 8787 -la 1 -version SAME -defaultweight 200
-defaultweight <WEIGHT>
Specify the default weight for this site. This weight is used if no weight is specified for this site on any resource.
-port <PORT>
Specify the port for this site. Note, when using SSL, it is essential to specify the web port of the NC instance, and not the VOV port. This option may be omitted ONLY if using -autodetect.
-access <ACCESS_METHOD>
This option is deprecated. The only available access is now vtk.
-ssl <BOOLEAN>
Specify whether this site is SSL enabled or not.
-version <VERSIONID>
Specify the VOV software version of the remote site. This allows the use of different versions at different sites. The default value is 'SAME' to mean the same version used by Allocator.
-lsf
Declare this to be a LSF site. For this type of site, other options shown below apply.
-lsfdur BOOLEAN
Only for LSF sites. This option controls whether to honor the duration=N statement in rusage[]. The default value is 0, which ignores the duration statement.
-user USER
Only for LSF sites. This is the name of the user that runs bjobs on the remote host where LSF is running. The 'user' is used in a 'ssh user@host ...' command.
-lsfdir DIR
Only for LSF sites. This is the directory on the remote LSF host in which to run the bjobs command. This option is explained in detail in PBS and Other Queues.
-local-bjobs-file FILE
Only for LSF sites. Only for debugging. Please do not use.
-timezone TZ
Only for LSF sites. The Time Zones in which the LSF master is running.
-autodetect
Automatically detect the host and port from the registry, for the specified Accelerator site. This option has no effect for LSF or PBS.
Examples
LA::AddSite vnc@jupiter    US {} -version 2016.03  -port 7788
LA::AddSite vnc_ca@calnx03 CA {} -version SAME     -port 6227 -defaultweight 200
LA::AddSite vncx2@--       IN {} -autodetect -version SAME  -defaultweight 200
LA::AddSite lsv1@ux01      NY {} -defaultweight 330  -scheduler LSF -lsfdur 1  -lsfdir ./lsf_la_dir -timezone EST5EDT
LA::AddSite pbs1host    PBS1 {} -defaultweight 330  -scheduler PBS

LA::DefineUserMap

Description
For some machines, assume that a specified user is using the licenses. Used on installation that include both Windows and UNIX taskers in which the Windows hosts may be running as a different user from the one that submitted the job.
Usage
LA::DefineUserMap <HOST_PATTERN> <USER>
Required Arguments
<PATTERN>
Hostname glob pattern.
<USER>
User name to be used for all information referring to the hosts matching the pattern.
Examples
# The actual user of licenses on machines that match the string 'farm1' is actually sysmgr.
LA::DefineUserMap farm1    sysmgr

# The user of licenses on machines that match 'farm[a-z]' is actually bspice.
LA::DefineUserMap farm[a-z]  bspice

# The users on machines called like winJ.* are mapped to user "john".
LA:DefineUserMap winJ.* john

LA::DefineRemoteResourceName

Description
By default, the name of the resourcemap on each site is the name declared in the LA::AddResource statement. Sometimes, however, a resourcemap should have different names on different sites.
Usage
LA::DefineRemoteResourceName <SITE@HOST> <SHARED_RESOURCE> <REMOTENAME>
Required Arguments
<SITE@HOST>
Site name or nickname.
<SHARED_RESOURCE>
Shared resource name
<REMOTENAME>
Remote resource name.
Examples
# On the site vnc@comet the name to be used for resource
# License:spice is old_spice.
LA::DefineRemoteResourceName vnc@comet   License:spice   old_spice
LA::DefineRemoteResourceName vnc@ny      License:spice   license_spice

LA::SetMapForResourceInSite

Description
This procedure allows using different maps on each Accelerator site for each resource managed by Allocator. This only applies to Accelerator sites, not to LSF sites. This procedure provides fine control on the resource map of a resource in a site. This may be used to change the order of components in resource groups. To delete the map, use the value "-" for MAP.
Required Arguments
<SITE>
Site name or nickname.
<RESOURCE>
Name of a resource
<MAP>
Map to be used.
Examples
# The users on machines called like winJ.* are mapped to user "john"
#   US before EU licenses.
LA::SetMapForResourceInSite SanJose License:ncsim "License:US_ncsim OR License:EU_ncsim"
#   EU before US licenses.
LA::SetMapForResourceInSite Munich  License:ncsim "License:EU_ncsim OR License:US_ncsim"
#   Use default value.
LA::SetMapForResourceInSite Pudong  License:ncsim -

LA::SetMinQuantity

Description
Define a minimum amount of a resource to assign to a site even if the demand for that site is zero, that is, the site is in stand-by with respect to that resource.
Required Arguments
<SITE>
Site name or nickname.
<RESOURCE>
Name of a resource
<N>
Minimum number of tokens assigned to the site even if there is no demand.
Examples
### Allocate at least 3 tokens of License:abc to site with nickname NY
LA::SetMinQuantity NY License:abc 3
Comments
If unset, Allocator will need to be restarted. To avoid restarting, change the min/max values as follows:
2016.09 releases:
LA::SetMinQuantity <site> <resource> -1
 LA::SetMaxQuantity <site> <resource> -1
2017 releases:
LA::SetMinQuantity <site> <resource> NO_MIN
 LA::SetMaxQuantity <site> <resource> NO_MAX

LA::SetMaxQuantity

Description
Define the maximum amount of a resource to assign to a site even if the demand for that site is high.
Required Arguments
<SITE>
Site name or nickname.
<RESOURCE>
Name of a resource
<N>
Maximum number of tokens assigned to the site even if there is no demand.
Examples
### Allocate at most 25 tokens of License:abc to site with nickname NY
LA::SetMaxQuantity NY License:abc 25

LA::SetReserveForUser

Description
Reserve tokens for out-of-queue users. You can reserve tokens for any named user or for anybody by using the string "*" as user name.
Required Arguments
<RESOURCE>
Name of a resource to be reserved.
<USERSPEC>
The user for whom the resource is reserved. Could be * for 'any user'
<TOKENS>
Number of tokens to be reserved.
Examples
#
# Allow 8 out-of-queue tokens for user edward and 10 overall.
#
LA::SetReserveForUser License:abc edward 8
LA::SetReserveForUser License:abc *     10

LA::SetResourceWeight

Description
Set the weight of a resource for a site.
Required Arguments
<SITE>
Site name or nickname.
<USERSPEC>
The user for whom the resource is reserved. Could be * for 'any user'
<TOKENS>
Number of tokens to be reserved.
Examples
#
# Allow 8 out-of-queue tokens for user edward and 10 overall.
#
LA::SetReserveForUser License:abc edward 8
LA::SetReserveForUser License:abc *     10

LA::GetResourceField

Description
Get the value of a specific field from the resource.
Required Arguments
<SITE>
Site name or nickname.
<RESOURCE>
Name of a resource
<FIELD>
The field whose value needs to be obtained. The list of fields that can be queried through this procedure can be obtained by running the following command:
vovselect FIELDNAME from LAALLOCATIONS
<DEFAULT>
Default value to be returned if the value of this field cannot be obtained.
Examples
LA::GetResourceField A License:a WEIGHT
LA::GetResourceField B License:x PRIORITY

LA::GetSiteField

Description
Get the value of a specific field from the site.
Required Arguments
<SITE>
Site name or nickname.
<FIELDS>
The fields whose value needs to be obtained (comma separated). The list of fields that can be queried through this procedure can be obtained by running the following command:
vovselect FIELDNAME from LASITES
<DEFAULT>
Default value to be returned if the value of this field cannot be obtained.
Examples
LA::GetSiteField A SSLENABLED
LA::GetSiteField B VERSION

LA::SetMinExpirationTime

Description
Get the value of a specific field from the site.
Required Arguments
<MIN_EXPIRATION_TIME>
Minimum expiration time for the resources managed to Allocator.
Examples
LA::SetMinExpirationTime 5m

LA::SetRank

Description
Set the rank of this Allocator instance. If resources are managed by multiple Altair Accelerator products such as Allocator or Accelerator, the highest ranked product wins.
Required Arguments
<RANK>
The rank for this Allocator instance. Rank must be between 20 and 1000.
Examples
LA::SetRank 35

LA::ReloadHistoricalMetrics

Description
This command has been deprecated as this functionality is now included by default in Allocator.