`hopen`, `hclose`¶

hopen connect a process or file hclose disconnect a process or file

Kdb+ communicates with the file system and other processes through

one-shot functions
handles to persistent connections

Connections are opened and closed respectively by hopen and hclose.

`hopen`¶

Open a connection to a file or process

hopen filehandle
hopen processhandle
hopen (communicationhandle;timeout)
hopen port

Where

filehandle is a symbol atom (or string since V3.6 2017.09.26)
communicationhandle is a symbol atom (or string since V3.6 2017.09.26)
timeout is milliseconds as an integer
port is a local port number as an integer atom

connects to a file object or a communication handle, and returns a connection handle as an int.

hopen ":path/to/file.txt"                   / filehandle
hopen `:unix://5010                         / localhost, Unix domain socket
hopen(":10.43.23.198:5010";10000)           / IP address and timeout
hopen 5010                                  / local port number

For IPC compatibility, it serializes to {hopen x}. e.g.

hopen each(`:mysymbol;
        ":mycharvector";
        `:localhost:5000;
        ":localhost:5000";
        (`:localhost:5000;1000);
        (":localhost:5000";1000))

`hclose`¶

Close a connection to a file or process

hclose x     hclose[x]

Where x is a connection handle, closes the connection, and destroys the handle. The corresponding integer can then no longer be applied to an argument.

q)show h:hopen `::5001
3i
q)h"til 5"
0 1 2 3 4
q)hclose h
q)h"til 5"
': Bad file descriptor

Async connections: pending data on the connection handle is not sent prior to closing. If flushing is required prior to close, this must be done explicitly. (Since V3.6 2019.09.19)

q)neg[h][];hclose h;

hclose before V3.6 2019.09.19

If the handle refers to a WebSocket, hclose blocks until any pending data on the connection handle has been sent.

Files¶

If a filehandle specifies a non-existent filepath, it is created, including directories.

q)hdat:hopen ":f.dat"             / data file (bytes)
q)htxt:hopen ":c:/q/test.txt"     / text file

Passing strings instead of symbols avoids interning of such symbols.

This is useful if embedding frequently-changing tokens in the username or password fields.

Do not use colons in a file-path. It conflicts with the pattern used to identify a process.

To append to these files, the syntax is the same as for IPC:

q)r:hdat 0x2324
q)r:htxt "some text\n"
q)r:htxt ` sv("asdf";"qwer")

Processes¶

Communication handles¶

A communication handle specifies a network resource, and may include authentication credentials for it. There are four forms.

TCP: `:host:port[:user:password]; host can be a hostname or IP address; omitted, it denotes the localhost
Unix domain socket: `:unix://port[:user:password]; (Since V3.4.) Unix domain sockets can have significantly lower latency and higher throughput than a localhost TCP connection
SSL/TLS: `:tcps://host:port[:user:password]; SSL/TLS
Fifo/named pipe: `:fifo://filename; On Unix builds since V3.4.

hopen `:10.43.23.198:5010                    / IP address
hopen ":mydb.us.com:5010"                    / hostname
hopen `::5010                                / localhost
hopen 5010                                   / localhost
hopen `:unix://5010                          / localhost, Unix domain socket
hopen `:tcps://mydb.us.com:5010              / SSL/TLS with hostname
hopen (`:mydb.us.com:5010:elmo:sesame;10000) / full arg list, 10s timeout

User and password are required if the server session has been started with the -u or -U command line options, and are passed to .z.pw for (optional) additional processing.

The optional timeout applies to the initial connection, not subsequent use of it.

To send messages to the remote process:

q)h"2+2"          / synchronous (GET)
4
q)(neg h)"a:2"    / asynchronous (SET)

One-shot request¶

If only one synchronous query/request is to be run, then the one-shot synchronous request can be used to connect, send the query, get the results, then disconnect.

q)`:mydb.us.com:5010:elmo:sesame "1+1"
2

It is more efficient to keep a connection open if there is an opportunity to re-use it for other queries.

One-shot sync queries can now execute via `::[(":host:port";timeout);query]. (Since V4.0 2020.03.09.)

`::[(":localhost:5000:username:password";5000);"2+3"]

":host:port" can also be a symbol as `:host:port.

.Q.Xf (create file)
Communication handle, Connection handle, File system, Interprocess communication
Client-server, Named pipes, SSL/TLS
Q for Mortals §11.6.2 Opening a Connection Handle

hopen, hclose¶

hopen¶

hclose¶