Skip to content

IPC

APIs for opening, closing and maintaining IPC handles.

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

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.

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

Handle Info

Return meta information about handles registered against this process.

.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