Skip to content

Configuration

Set of APIs for interacting with the configuration parameters in Control. These parameters are sets of tables defined in Control, used to configure the system. Each parameter can have its own schema definition, defined in DEFAULT override, and each override can have different rows and values. This can be used to set different behavior depending on the system, host, process etc.

Static Configuration

A process can call to Control to retrieve configuration for a given parameter and override using .uc.getActiveParamValue. If the parameter is static or rarely changed, it should be retrieved once during the start-up phase and cached as a variable. Repeatedly calling to Control to retrieve parameters is not advised as it increases load and risks blocking the process.

Dynamic Configuration

For frequently changing configuration it's advised to subscribe to the parameter using .uc.getAndSaveActiveParamValue. This caches the parameter locally in a variable from where it can be directly accessed and is updated automatically whenever the Control version changes. Actions to run on receiving a change can also be specified. Parameters can also be edited using .uc.editActiveSingleParamData.

In cases where the list of overrides might not be known in advance or the user doesn't want to worry about providing variable cache names, a utility script has been provided as an instruction in Stream called Configuration. This wraps the calls of this module but handles the specified cases.

.uc.editActiveSingleParamData

Called to update a configuration parameter in Control. Schema of the table must match the schema of the DEFAULT override. The call is synchronous.

Parameters:

Name Type Description
param symbol Parameter name
orride symbol Override name
data table Table of updated details

Example:

 .uc.editActiveSingleParamData[`DS_EMAIL_SERVER; `DEFAULT; ([] MAIL_HOST:`fd01; MAIL_PORT:`25; MAIL_FROM:enlist `$"deltamon@firstderivatives.com")]

.uc.getActiveParamValue

Gets a configuration parameter from Control. If the override is blank or not configured, it will return the DEFAULT.

Parameters:

Name Type Description
paramName symbol Parameter name
profOverride symbol Override name

Returns:

Type Description
table Returns table of configuration

Example: Override specified

 .uc.getActiveParamValue[`DS_MESSAGING_SERVER; `DS]
 /=> instance
 /=> --------
 /=> ds_ms_a
 /=> ds_ms_b

Example: Override not specified, default used

 .uc.getActiveParamValue[`DS_MESSAGING_SERVER; `]
 /=> instance
 /=> --------
 /=>

.uc.getAndSaveActiveParamValue

Subscribes to a configuration parameter in Control. User specifies a local variable name to save the parameter to. When the parameter updates, the in-memory variable will be updated accordingly. The dictionary parameter allows the user to optionally specify key columns and actions to take when the parameter updates.

Warning

If the parameter has one column, the results will be returned as a list instead of a table.

The action will not be run automatically on initial call to .uc.getAndSaveActiveParamValue

Parameters:

Name Type Description
paramName symbol Parameter name
profOverride symbol Override name
variableName symbol Name of variable to save to
dict dict Allowed keys are; keyCols {symbol[]} List of columns to key the saved details by, action {string|functional} An action to run when the parameter updates. Can be a functional form or string, will be executed using value

Returns:

Type Description
table|list Returns the parameter details. List format returned if parameter only has one column.

Example: With key columns and action as functional form

 .uc.getAndSaveActiveParamValue[`DS_EMAIL_SERVER; `DEFAULT; `.email.server; `keyCols`action!(`MAIL_HOST; (`updateEmailServers; `))]
 /=> MAIL_HOST| MAIL_PORT MAIL_FROM
 /=> ---------| ---------------------------------------
 /=> fd01     | 25        deltamon@firstderivatives.com

Example: Action only. In string form

 .uc.getAndSaveActiveParamValue[`DS_EMAIL_SERVER; `DEFAULT; `.email.server; enlist[`action]!enlist "updateEmailServers[]"]
 /=> MAIL_HOST MAIL_PORT MAIL_FROM
 /=> -------------------------------------------------
 /=> fd01      25        deltamon@firstderivatives.com

Example: No action or key columns specified. Result returned as list

 .uc.getAndSaveActiveParamValue[`DS_MESSAGING_SERVER; `DS; `.dm.dmservername; ()!()]
 /=> `ds_ms_a`ds_ms_b

.uc.getAndSaveAllParam

Subscribes to all overrides of a configuration parameter including newly added ones. An internal variable is created to save the parameter data to for each override. When the parameter updates, the in-memory variable will be updated accordingly.

Parameters can be retrieved using .uc.getSavedData.

Key columns can be specified and also a callback defining actions to take when each parameter updates. The action should be the name of a function or a lambda taking one parameter. It will be called with the name of the changed override.

Warning

The action will not be run automatically on initial call to .uc.getAndSaveAllParam

Parameters:

Name Type Description
param symbol Parameter name
keyCols symbol[] Columns to key by
callback lambda|functional Action to run when an override updates

Returns:

Type Description
symbol[] List of existing overrides

Example: With key column and functional callback

 logOverrideChange:{[x] .log.out[.z.h; "parameter update"; x]}
 .uc.getAndSaveAllParam[`DM_ColourThresholds; `sym; `logOverrideChange]
 0N!overrides:.uc.getSavedOverrides[`DM_ColourThresholds]
 /=> `DEFAULT`ProcessCPU`ProcessMemory`ServerCPU`ServerFileSystem`ServerMemory
 logOverrideChange'[overrides]
 .uc.getSavedData[`DM_ColourThresholds; `ProcessCPU]
 /=> sym           minThreshold maxThreshold
 /=> ---------------------------------------
 /=> DEFAULT       0            50
 /=> RDB           0            10
 /=> RTE           0            1
 /=> DeltaControl  0            1

Example: With key columns and projection for the callback

 logParamChange:{[x;y] .log.out[.z.h; "parameter update"; ":" sv (string x;string y)]}
 .uc.getAndSaveAllParam[`DM_ALERT_PARAMETERS; `sym`warningThreshold; logParamChange[`DM_ALERT_PARAMETERS;]]
 0N!overrides:.uc.getSavedOverrides[`DM_ALERT_PARAMETERS]
 /=> `DEFAULT`MemoryUsage`Server1MinLoad`ServerCPU
 logParamChange[`DM_ALERT_PARAMETERS;]'[overrides]

.uc.getSavedData

Called to get parameter data for an override. Used in conjunction with .uc.getAndSaveAllParam where parameters are saved to hidden variables.

Parameters:

Name Type Description
parameter symbol Parameter
overr symbol Override

Returns:

Type Description
table Parameter data

Example:

 .uc.getSavedData[`DM_ColourThresholds; `ProcessCPU]
 /=> sym           minThreshold maxThreshold
 /=> ---------------------------------------
 /=> DEFAULT       0            50
 /=> RDB           0            10
 /=> RTE           0            1
 /=> DeltaControl  0            1

.uc.getSavedOverrides

Gets the list of existing overrides for a parameter

Parameter:

Name Type Description
parameter symbol Parameter

Returns:

Type Description
symbol[] List of overrides

Example:

 .uc.getSavedOverrides[`DM_ColourThresholds]
 /=> `DEFAULT`ProcessCPU`ProcessMemory`ServerCPU`ServerFileSystem`ServerMemory

.uc.republishUpdates

Calls to Control to push out config updates to all processes subscribed for those entities in the table provided. This will be the latest config entity version up to the active version number associated with the process

Parameter:

Name Type Description
entTab table Entity table of parameter name and override

Returns:

Type Description
Nothing returned

Example:

 tab:([]parameter:`TestParam101`TestParam202;override:`DEFAULT`DEFAULT)
 .uc.republishUpdates[tab]
 /=> ::