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.deleteParam

Deletes a configuration parameter from Control.

Parameters:

Name	Type	Description
pName	symbol	Name of config parameter
pOverride	symbol	Override

Example:

 .uc.deleteParam[`new_parameter;`DEFAULT]

.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. Retrieves the parameter at the version the process is operating at.

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

Initially retrieves the parameter at the version the process is operating at. If the process is not operating at the latest version, updates will only be received when .uc.republishUpdates is invoked

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

Initially retrieves the parameter at the version the process is operating at. If the process is not operating at the latest version, updates will only be received when .uc.republishUpdates is invoked

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.getParamVer

Calls to Control to get the list of overrides for a parameter along with the config tables. This will be the state of the parameter and overrides at the version specified

Parameters:

Name	Type	Description
param	symbol	Parameter name
ver	long	Version number

Returns:

Type	Description
dict	Override names with values corresponding to the config tables

Example:

 param:`DC_EXPORT_FILES
 ver:2000j
 .uc.getParamVer[param; ver]
 /=> DEFAULT    | +`directory`file!(,`;,`)
 /=> DeltaStream| +`directory`file!(`ENV=DELTADOCGENREPORTJRXMLS_EXAMPLES=`ENV=DELTADOCGEN_RESOURCES=;`*`*)

.uc.getSavedData

Called to get parameter data for an override. Used in conjunction with .uc.getAndSaveAllParam where parameters are saved to hidden variables. Reads parameter data from local cache and therefore will return data at the version the process is operating at.

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. Reads this from the local cache and therefore will return the list at the version the process is operating at.

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, or a subset of process instances 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. If the config entity has been deleted at the active version number for a process, the subscription to it will be removed when .uc.republishUpdates is called with the process in the list to publish to. The process handle will be removed from the subscriber list for that config entity on Control. If the active version of a process is changed, .uc.republishUpdates should be called for the process to push out any relevant config updates for it's new active version

Parameters:

Name	Type	Description
entTab	table	Entity table of parameter name and override
procs	symbol[]	List of process instances to publish to, `all for all, empty list to publish to calling handle only

Returns:

Type	Description
	Nothing returned

Example:

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