Skip to content

IPC

APIs for opening, closing and maintaining IPC handles.

.px.ipc.getAlternates

Gets the list of alternate IPs for a set of hosts. If no alternates exist for a host, returns the input host

Parameter:

Name Type Description
hosts symbol[] Host list

Returns:

Type Description
symbol[][] IP alternates list

Example:

 hosts:`server1`server2;
 ips:(`192.168.0.1`171.30.0.1; `192.168.0.2`171.30.0.2);
 .px.ipc.setAlternates[hosts; ips];
 .px.ipc.getAlternates[hosts]
 /=> (`192.168.0.1`171.30.0.1; `192.168.0.2`171.30.0.2)

Example:

 0N!.px.ipc.getAlternates[1#`foo];
 /=> ,,`foo

.px.ipc.setAlternatesFromFile

Read a host alternates file and set the alternate list.

Parameter:

Name Type Description
file symbol File path

Example:

 file:hsym .utils.checkForEnvVar["ENV=DELTA_CONFIG=/host_alternates.csv"];
 .px.ipc.setAlternatesFromFile[file];

.px.ipc.setAlternates

Sets the list of alternate IPs for a set of hosts.

Parameters:

Name Type Description
hosts symbol[] Host list
ips symbol[][] IP alternates list

Example:

 host:`server1`server2`server1.domain.com;
 ips:(`192.168.0.1`171.30.0.1; `192.168.0.2`171.30.0.2; `192.168.0.1`171.30.0.1);
 .px.ipc.setAlternates[hosts; ips];

.px.ipc.tryEnable

Assesses if parallel connectivity is supported

Parameter:

Name Type Description
cfg Boolean If this parameter is true support for parallel connectivity will be assessed

Returns:

Type Description
Boolean True if parallel connectivity supported

Example:

 .px.ipc.tryEnable[.pl.cfg.i.getParam[`.dm.i.retryParallel]]
 /=> 1b

.utils.closecon

Closes an IPC handle. Uses hclose but does not trigger .z.pc.

Parameter:

Name Type Description
x int Handle

Example:

 .utils.closecon[6i]

.utils.dccAlt

Uses .px.ipc.phopenAlt to open connections in parallel with alternates. Otherwise exhibits the same behaviour as .utils.dcc with respect to credentials and deltacomponent.

Parameters:

Name Type Description
c symbol Connection string
t long Timeout value in milliseconds. Null or zero for no timeout
e fn Function or projection with one parameter to handle connection error

Returns:

Type Description
int Integer handle

Example:

 hp:`:localhost:5000;
 .utils.dccAlt[hp; 1000; {'x}]

.utils.dccMode

Wrapper function for .utils.dcc that builds hopen string but includes a connection mode to account for TLS or UDS. Can connect as deltacomponent by using a null user.

Parameters:

Name Type Description
host symbol Host name
port int Port number
user symbol Username
pass string Password
mode symbol Connection mode - standard TCPIP, UDS or TLS
timeout long Open connection timeout
trapF func Function to handle connection error

Returns:

Type Description
int Connection handle

Example:

 .utils.dccMode[`localhost; 5000i; `; ""; `tls; 0; {0Ni}]
 /=> 5i

Example:

 .utils.dccMode[`localhost; 5000i; `; ""; `uds; 1000; { -2"Connection failed: ",x; 0Ni}]
 /=> 5i

.utils.dcc

Opens a handle to a host and port. Can be called with or without user credentials. If called without credentials but a set of conditions are satisified, the handle will be opened as an internal Control user, deltacomponent.

The set of conditions are;

  • Process template file is in a allowlist of core Control templates
  • Not being invoked as part of another IPC call (.z.w=0)
  • Or if invoked in an IPC call, the remote user (.z.u) is also deltacomponent

deltacomponent user

If deltacomponent is configured as a non-administrator user then requests on handles opened using this API will be subject to permission checks. For more information see the KX Control documentation here

Parameters:

Name Type Description
c symbol Connection string, with or without user credentials
t long Timeout value in milliseconds. Null or zero for no timeout
e fn Function or projection with one parameter to handle connection error

Returns:

Type Description
int Integer handle

Example:

 hp:`:localhost:5000;
 errF:{[h;e] .log.out[.z.h; "Error connecting to ",string[h]; e]; 0Ni};
 .utils.dcc[hp; 1000; errF[hp;]]
 /=> 4i

Example:

 hp:`:localhost:5000:user:password;
 .utils.dcc[hp; 0Ni; {0Ni}]
 /=> 5i

.utils.opencon

Opens an IPC or file handle. Acts as a wrapper for hopen. Returns -1i if the open was unsuccessful.

Parameter:

Name Type Description
x symbol Connection string

Returns:

Type Description
int Handle value

Example:

 .utils.opencon[`:localhost:5000]
 /=> 5i

.ch.addExit

Add a process exit handler. The function should take one parameter and will be triggered when .z.exit is called.

Parameter:

Name Type Description
functionName symbol Function name

Example:

 .ch.addExit[`cleanHandles]

.ch.addPC

Add a close connection handler. Should take one parameter and will be triggered when .z.pc is called.

Parameter:

Name Type Description
functionName symbol Function name

Example:

 .ch.addPC[`closeHandles]

.ch.addPO

Add an open connection handler. Should take one parameter and will be triggered when .z.po is called.

Parameter:

Name Type Description
functionName symbol Function name

Example:

 .ch.addPO[`openHandles]

.ch.deleteExit

Removes a process exit handler.

Parameter:

Name Type Description
functionName symbol Function name

Example:

 .ch.deleteExit[`cleanHandles]

.ch.deletePC

Removes a close connection handler.

Parameter:

Name Type Description
functionName symbol Function name

Example:

 .ch.deletePC[`closeHandles]

.ch.deletePO

Removes an open connection handler.

Parameter:

Name Type Description
functionName symbol Function name

Example:

 .ch.deletePO[`openHandles]

.ch.getHandle

Returns the client handle (.z.w)

Returns:

Type Description
int Client handle

Example:

 .ch.getHandle[]
 /=> 3i

.ch.getHost

Get the host of the remote handle

Parameter:

Name Type Description
x int IPC handle

Returns:

Type Description
symbol Remote host

Example:

 .ch.getHost[6i]
 /=> `remotehost

.ch.getName

Get the name registered for a handle

Parameter:

Name Type Description
x int IPC handle

Returns:

Type Description
symbol Process name

Example:

 .ch.getName[6i]
 /=> `ds_qp_a.1

.ch.getPID

Get the PID registered for a handle

Parameter:

Name Type Description
x int IPC handle

Returns:

Type Description
int Process PID

Example:

 .ch.getPID[6i]
 /=> 12968i

.ch.getStatus

Get the status of a handle

Parameter:

Name Type Description
x int IPC handle

Returns:

Type Description
symbol Handle status

Example:

 .ch.getStatus[6i]
 /=> `opened

.ch.getType

Returns flag indicating if handle is to platform or external process

Parameter:

Name Type Description
x int IPC handle

Returns:

Type Description
boolean True for non-platform process

Example:

 .ch.getType[3i]
 /=> 1b

.px.ipc.close

Closes a remote connection and trigger the .z.pc callback.

Parameter:

Name Type Description
handles int[] Handle list

Example:

 .px.ipc.close[5 6i];

.px.ipc.phopenAlt

Connects to a target process by looking up the alternates for it, building the connection strings and passing the results to .px.ipc.phopen Returns handle numbers for valid connections and null for others.

Parameters:

Name Type Description
hosts symbol[] List of hosts
ports int[] List of ports
protocols symbol[] Connection protocols (null, tls, uds)
timeout long Connection timeout
validator null Request to run to validate process state
user symbol Connection user
password string Connection password

Returns:

Type Description
int[] List of handles

Example: Two targets with one set of alternative IPs

 hosts:`server1`server2;
 ports:5000 5001i;
 ips:(`192.168.0.1`171.30.0.1; `192.168.0.2`171.30.0.2);
 .px.ipc.setAlternates[hosts; ips];
 0N!handles:.px.ipc.phopenAlt[hosts; ports; count[hosts]#`; 1000; (`.r.isLeader; (::)); `Administrator; "password"]
 /=> 0N 5i

.px.ipc.phopenDcc

Acts as a wrapper to .px.ipc.phopenAlt but takes a connection string as an input. Used by .utils.dccAlt as a means to use deltacomponent with phopen. Will split the connection string and figure out the targets, protocol, and credentials.

Parameters:

Name Type Description
hp symbol[] Connection string
timeout long Connection timeout

Returns:

Type Description
int | null Handle or 2 element list for error

Example:

 hosts:`server1`server2;
 ports:5000 5001i;
 ips:(`192.168.0.1`171.30.0.1; `192.168.0.2`171.30.0.2);
 .px.ipc.setAlternates[hosts; ips];
 hp:.utils.getHostPortOnly[`localhost; 6000; `];
 0N!handle:.px.ipc.phopenDcc[hp; 1000];
 /=> 5i

 hp:.utils.getHostPortOnly[`localhost; 6000; `tls];
 0N!handle:.px.ipc.phopenDcc[hp; 1000];
 /=> (`err; "phopen connection failed")

.px.ipc.phopen

Implements a parallel hopen to a host/port and alternatives. Each connection attempt uses the specified timeout and runs a validation command on the target process to check its state (must return a boolean). Returns handle numbers for valid connections and null for others.

The what parameter is a list of alternatives for the host/port details.

Parameters:

Name Type Description
what symbol[][] Vector of host/port alternatives
timeout long Connection timeout
validator null Request to run to validate process state

Returns:

Type Description
int[] List of handles

Example: Four targets with one set of alternative IPs

 hps:(`:192.186.1.1:5000:Administrator:password`:172.31.0.174:5000:Administrator:password;
      `:192.186.1.2:5000:Administrator:password`:172.31.0.175:5000:Administrator:password;
      `:192.186.1.3:5000:Administrator:password`:172.31.0.176:5000:Administrator:password;
      `:192.186.1.4:5000:Administrator:password`:172.31.0.177:5000:Administrator:password);
 0N!handles:.px.ipc.phopen[hps; 1000; (`.r.isLeader; (::))]
 /=> 0N 5 0N 0Ni

Example: Multiple leaders

 0N!handles:.px.ipc.phopen[hps; 1000; (`.r.isLeader; (::))]
 /=> 0N 5 0N 6i

Callbacks

The following functions serve as wrappers to internal kdb+ callbacks for handles opening (.z.po), closing (.z.pc) and process exits (.z.exit). Multiple custom handlers can be added and removed using the listed functions.

Handle Info

Return meta information about handles registered against this process.