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 satisfied, 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 alsodeltacomponent
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 KX Delta Platform or external process
Parameter:
| Name | Type | Description |
|---|---|---|
| x | int | IPC handle |
Returns:
| Type | Description |
|---|---|
| boolean | True for non-KX Delta 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.