Runtime

This module contains APIs to manage the process state. This includes;

• Reporting to and loading required process state from Control
• Getting details of other processes
• Maintaining handles to and querying other processes

.pl.sendemail

Deprecated: Use Email module

Calls to Control and sends an email via the Alerts framework. Function takes a dictionary and must have to, sub, body keys. Can optionally specify files via the file_list key. The files must exist on the same server as the email RTE.

Parameter:

Name	Type	Description
emailDict	dict	Email data

Returns:

Type	Description
boolean	True if successfully sent to alert framework

Example:

 .pl.sendemail[`to`sub`body!(`$"user1@fd.com"; "Subject"; "Message text")]
 /=> 1b

.rpl.isLeader

Check whether process is leader.

Returns:

Type	Description
boolean	Leader status

Example:

 .rpl.isLeader[]
 /=> 1b

updEntityChange

Deprecated: Use Entity Subscriptions module

Called when Control pushes an update to say an entity is changed. Stub function is defined as empty but left as a hook for user-code to overwrite.

Parameters:

Name	Type	Description
class	symbol	Entity class
entity	symbol	Entity name
dict	dict	Dictionary containing one symbol key action

Example:

 param:.pm.createname[`delta_install_default`DS_EMAIL_SERVER`DEFAULT]
 updEntityChange[`configparam; param; `update]

.ex.prh

Function to handle synchronous communication with Control. Parameter is the query to be executed. The query will be executed as deltacomponent user.

If the Control connection is down, it will immediately try to reconnect before throwing an exception.

deltacomponent user

If deltacomponent is configured as a non-administrator user then the request will be subject to permission checks. For more information see the KX Control documentation here

Parameter:

Name	Type	Description
	query	Query

Returns:

Type	Description
untyped	Result of query

Example:

 .ex.prh[(`.pl.getRunningInformation; `)]

.ex.getdetails

Get parameter details for a given instance. Resolves any environment variables locally or uses the Control value if local isn't defined.

Parameter:

Name	Type	Description
x	symbol	Instance name

Returns:

Type	Description
dict	Instance parameters

Example:

 .ex.getdetails[`ds_rdb_ops_a]
 /=> time         | 00:00:00.000
 /=> sym          | `
 /=> name         | `DS_RDB
 /=> paramvalues  | `dc_host`dc_port`dc_taskset`dc_algroups`dc_additionalFiles..
 /=> defaultparams| `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> apps         | `symbol$()
 /=> reqparams    | `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> optparams    | `dc_taskset`dc_algroups`dc_additionalFiles`dc_timeout..
 /=> desparams    | `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> directory    | `/
 /=> file         | `DS_RDB.q
 /=> argtypes     | `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> prdes        | "DeltaStream RealTimeSubscriber Process template"
 /=> returnstat   | (`symbol$())!`symbol$()
 /=> description  | `DeltaStream RealTimeSubscriber Process template
 /=> inherit      | 0b

.ex.getdetailsforTask

Get parameter details for a given task. Resolves any environment variables locally or uses the Control value if local isn't defined.

Parameter:

Name	Type	Description
x	symbol	Task name

Returns:

Type	Description
dict	Task parameters

Example:

 .ex.getdetailsforTask[`ds_rdb_ops_a.1]
 /=> time         | 00:00:00.000
 /=> sym          | `
 /=> name         | `DS_RDB
 /=> paramvalues  | `dc_host`dc_port`dc_taskset`dc_algroups`dc_additionalFiles..
 /=> defaultparams| `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> apps         | `symbol$()
 /=> reqparams    | `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> optparams    | `dc_taskset`dc_algroups`dc_additionalFiles`dc_timeout..
 /=> desparams    | `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> directory    | `/
 /=> file         | `DS_RDB.q
 /=> argtypes     | `messagingServer`subscriptionChannel`subscriptionTableList..
 /=> prdes        | "DeltaStream RealTimeSubscriber Process template"
 /=> returnstat   | (`symbol$())!`symbol$()
 /=> description  | `DeltaStream RealTimeSubscriber Process template
 /=> inherit      | 0b

.ex.getresultsbyid

Get results for a given process run ID

Parameter:

Name	Type	Description
	int	Run ID

Returns:

Type	Description
dict	Instance results

Example:

 .ex.getresultsbyid 16765
 /=> procname| ds_gw_fx_eval
 /=> status  | running
 /=> port    | 6034

.ex.loadfileNOERROR

Loads a q file from disk. Any errors will be trapped and reported to Control. A boolean will returned to indicate success.

Parameter:

Name	Type	Description
	symbol	Path to file for loading

Returns:

Type	Description
boolean	Load status

Example:

 .ex.loadfileNOERROR[`$":../shared/q/dbmaint.q"]

.ex.prhAsync

Function to handle asynchronous communication with Control. Parameter is the query to be executed. The query will be executed as deltacomponent user.

If the Control connection is down, it will immediately try to reconnect before throwing an exception.

deltacomponent user

If deltacomponent is configured as a non-administrator user then the request will be subject to permission checks. For more information see the KX Control documentation here

Parameter:

Name	Type	Description
	query	Query

Example:

 .ex.prhAsync[(`.ch.heartbeat; `)]

.ex.setRegHost

Sets the host to use for registration with Control. Should be called as part of a startup instruction. In order to run the it before registration, the instruction should be added to the .al.preStartupInstructions parameter of the INSTANCE_CONFIG override. The default value used is the result of .utils.gethost[]. To use the IP address, use the result of .utils.getlocalip[].

Parameter:

Name	Type	Description
host	symbol	Registration host

Example:

 .ex.setRegHost[`host]

.pl.getConnection

Gets details for a Control connnection.

Parameter:

Name	Type	Description
name	symbol	Connection name

Returns:

Type	Description
string	Connection string in hopen format

Throws:

Type	Description
	'notexist

Example:

 .pl.getConnection[`ds_rdb_fx_eval]
 /=> `:coredev1:6025

.pl.getParameters

Get instance and runtime parameters.

Returns:

Type	Description
dict	Generic and instance-specific parameters

Example:

 .pl.getParameters[]
 /=> entity_name           | `task.ds_tp_ops_a.1
 /=> messagingServer       | `configname`value`fullconfigname!(`DS_MESSAGING_SERVER:DS;+(,`instance)!,`ds_ms_a`ds_ms_b;`delta_install_default:DS_MESSAGING_SERVER:DS)
 /=> publishChannel        | `ds_tp_ops_a
 /=> subscriptionChannel   | `ds_ops
 /=> subscriptionTableList | `symbol$()
 /=> logDirectory          | `ENV=DELTAOPS_TPLOGDIR=
 /=> dsLsInstance          | (,`instancename)!,`
 /=> timeOffset            | 0i
 /=> pubFreq               | 100i
 /=> eodTime               | 00:00:00.000
 /=> initialStateFunct     | `analyticname`functioncode`function!(`dxEmptyFunctionNull;"{[]\n\n }";{[] })
 /=> logRecoveryFunct      | `analyticname`functioncode`function!(`dxEmptyFunction;"{[x;y]\n }";{[x;y] })
 /=> includeColumns        | 1b
 ...

.pl.getWorkflowParams

If process launched as part of a workflow, this function can be used to get parameters/results passed from the upstream tasks. Results are returned as a dictionary of upstream task IDs to serialised results. To de-serialise, use .utils.dsd.

Returns:

Type	Description
dict	Mapping of upstream task IDs to parameters

Example:

 .pl.getWorkflowParams[]
 /=> 164| 0x0100000036000000630b000200000070726f636e616d6500737461747573000000020000000a000700000074657374315f64f56f6b00
 /=> 163| 0x0100000036000000630b000200000070726f636e616d6500737461747573000000020000000a000700000074657374325f64f56f6b00

Example:

 .utils.dsd each .pl.getWorkflowParams[]
 /=>    | procname  status
 /=> ---| ----------------
 /=> 164| "test1_d" ok
 /=> 163| "test2_d" ok

.pl.gethostport

Get the connection string for an instance

Parameter:

Name	Type	Description
instanceName	symbol	Instance name

Returns:

Type	Description
symbol	Connection string

Example:

 .pl.gethostport[`ds_tp_ops_a]
 /=> `:localhost:6031

.pl.r.addReconnectFunction

Add a function to be executed after the Control connection is re-established after a disconnect.

Parameters:

Name	Type	Description
funct	symbol	Name of function to call. Should take no parameters
functParams	untyped	List of parameters to call with function

Example:

 logReconnect:{.log.out[.z.h;”New leader is”;.ex.prh”(.utils.gethost[];system\”p\”)”]}
 .pl.r.addReconnectFunction[`logReconnect;()]

.pl.r.deleteReconnectFunction

Remove a Control reconnect function.

Parameter:

Name	Type	Description
	symbol	Function name

Example:

 .pl.r.deleteReconnectFunction[`logReconnect;()]

.pl.return_exit

Return results to Control and shutdown. Used to indicate the process has finished successfully. Control uses this information for audit logging and to know when to initiate any downstream workflow tasks. By default all processes templates will call this after loading custom code and shutdown. Template code must call .pl.setexitblockedoncompletion to continue running.

Parameter:

Name	Type	Description
data	dict	Results for this instance run

Example:

 .pl.return_exit[`trade`quote!(10; 134)]

.pl.return_noexit

Return results to Control without shutting down.

Parameter:

Name	Type	Description
data	dict	Results for this instance run

Example:

 .pl.return_noexit[`trade`quote!(10; 134)]

.pl.runProcess

Run an instance or task from Control

Parameter:

Name	Type	Description
pr	symbol	Instance or task name

Example:

 .pl.runProcess[`ds_rdb_ops_a]

.pl.setexitblockedoncompletion

Default behavior of process templates will execute code, report results to Control and shutdown. Calling .pl.setexitblockedoncompletion ensures the process stays running after returning results.

Parameter:

Name	Type	Description
bExit	boolean	Stay running

Example:

 .pl.setexitblockedoncompletion[1b]

.ex.getEntityClass

Get entity type of current run; instance or task

Returns:

Type	Description
symbol	Task type

Example:

 .ex.getEntityClass[]
 /=> `task

.ex.getEntityName

Get entity name of self process. Entity class can be an instance or task.

Returns:

Type	Description
symbol	Entity name

Example:

 .ex.getEntityName[]
 /=> `task.ds_tp_ops_a.1

.ex.getFileName

Get location of template file

Returns:

Type	Description
symbol	File path

Example:

 .ex.getFileName[]
 /=> `:/home/dcore/core/install/dc-data/qsrc///DS_TP.q

.ex.getInstanceName

Gets the instance name. Returns instance even if running as task.

Returns:

Type	Description
symbol	Instance name

Example:

 .ex.getInstanceName[]
 /=> `ds_tp_ops_a

.ex.getName

Get name of running process

Returns:

Type	Description
symbol	Process name

Example:

 .ex.getName[]
 /=> `ds_tp_ops_a.1

.ex.getProcessName

Get process template name

Returns:

Type	Description
symbol	Template name

Example:

 .ex.getProcessName[]
 /=> `DS_TP

.ex.getRuntimeName

Get the runtime name of a process. If running as a service, always returns the runtime name. If running as an instance, returns the instance or task according to task parameter

Parameter:

Name	Type	Description
task	boolean	Return task name

Returns:

Type	Description
symbol	Process name

Example: Running as service

 .ex.getRuntimeName[0b]
 /=> `ds_tp_ops_2345
 .ex.getRuntimeName[1b]
 /=> `ds_tp_ops_2345

Example: Running as task

 .ex.getRuntimeName[0b]
 /=> `ds_tp_ops_a
 .ex.getRuntimeName[1b]
 /=> `ds_tp_ops_a.1

.pl.closehandle

Close a handle to an instance. Reciprocal operation for .pl.openhandle.

Parameter:

Name	Type	Description
instanceName	symbol	Instance name

Example:

 .pl.closehandle[`ds_tp_ops_a]

.pl.openhandle

Open a handle to a specific instance. If a handle has already been opened by this API, the existing handle will be returned. Can optionally specify credentials and a connection timeout. Calls to Control to get host and port details. Throws an exception if the handle can't be opened

Parameters:

Name	Type	Description
instanceName	symbol	Instance name
user	symbol	Username
password	symbol	Password
timeout	long	Connection timeout

Returns:

Type	Description
symbol	Handle

Example: Open with credentials and 100 millisecond timeouts

 .pl.openhandle[`ds_tp_ops_a; `user; `password; 100]
 /=> 5i

Example:

 .pl.openhandle[`ds_tp_ops_a; `; `; 0]
 /=> 'hop. OS reports: Connection refused

.pl.sendquery

Send a sync or async query to a named instance. Internally uses .pl.openhandle to get a handle to the process. Can optionally specify user, password and connection timeout parameters.

Parameters:

Name	Type	Description
bSync	boolean	Send sync query
instanceName	symbol	Target instance
query	executable	Query object
user	symbol	Username
password	symbol	Password
timeout	long	Connection timeout

Returns:

Type	Description
untyped	Returns a result or error for sync queries. Throws an exception if can't open a handle.

Example:

 .pl.sendquery[1b; `ds_rdb_ops_a; "select from dxSessionInfo"; `; `; 100]
 /=> time                          sym                                         action user          su..
 /=> -------------------------------------------------------------------------------------------------..
 /=> 2017.02.16D06:53:07.787278000 coredev1-56547-MTU6NTM6MDcvMDAwMDAzMDAwMDAw login  Administrator su..

.ex.err

Reports the run status to Control as an error.

Parameters:

Name	Type	Description
x	symbol	Usually set to .z.h
y	string	Error message to display
z	untyped	Additional data. Any q object

Example:

 .ex.err[.z.h; "Failed to initialize reference data"; `trade`quote!(10; 134)]

.ex.out

Reports information message to Control with data and log to standard out.

Parameters:

Name	Type	Description
x	symbol	Usually set to .z.h
y	string	Information message
z	untyped	Additional data. Any q object

Example:

 .ex.out[.z.h; "Initialised reference data"; `trade`quote!(10; 134)]

.ex.warn

Reports warning message to Control with data and log to standard out.

Parameters:

Name	Type	Description
x	symbol	Usually set to .z.h
y	string	Warning message
z	untyped	Additional data. Any q object

Example:

 .ex.warn[.z.h; "Initialised reference data"; `trade`quote!(10; 134)]

.pl.report_error_addInfo

Report an error to Control with message and payload.

Parameters:

Name	Type	Description
msg	string	Error string to report
data	untyped	Additional information about error. Format can be any q object

Example:

 .pl.report_error_addInfo["Failed to initialize reference data"; `trade`quote!(10; 134)]

.pl.report_error_and_terminate

Report an error to Control with message and shutdown.

Parameters:

Name	Type	Description
msg	string	Error string to report
data	untyped	Error payload

Example:

 .pl.report_error_and_terminate["Failed to initialize reference data"; `trade`quote!(10; 134)]

.pl.report_error

Report an error to Control with message.

Parameter:

Name	Type	Description
msg	string	Error string to report

Example:

 .pl.report_error["Failed to initialize reference data"]

Admin

Process info

APIs to get process meta information. These are useful when interfacing with Control when getting state for the task or instance.

Queries

These functions exist to query other processes. The user only needs to know the instance or task name and the API will do the rest. The .pl.sendquery function can then be used to execute sync or async queries.

Tip

The QR client framework offers a greater breadth of functionality; load-balancing, targeting groups of databases, group types (leaderCluster, round-robin).

Reporting

Set of APIs for reporting process state to Control. Logs messages to stdout logs of both processes. Control will generate alerts for these events.