Skip to content

hopen, hclose

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

Kdb+ communicates with the file system and other processes through handles.

File system, Interprocess communication

hopen

Syntax: hopen x, hopen[x]

Where x is one of

  • a process symbol
  • a 2-item list of a process symbol and a timeout in milliseconds
  • a file symbol or (since V3.6 2017.09.26) filename

opens communication to a file or a process, and returns a handle.

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

Processes

A process symbol has the form:

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

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.

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

To send messages to the remote process:

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

If only one synchronous query/request is to be run, then the one-shot synchronous request can be used to open a connection, send the query, get the results, then close the connection. It is more efficient to keep a connection open if there is an opportunity to re-use it for other queries.

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

.Q.Xf (create file)
Client-server

Files

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

Passing char vectors instead of symbols avoids interning of such symbols. This is useful if embedding frequently-changing tokens in the username or password fields.

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

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

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")

Fifo/named pipes

V3.4 Unix builds have support for reading from a Fifo/named pipe, where the hopen argument has the form `:fifo://filename.

File system, Client-server, Named pipes
SSL/TLS

hclose

Syntax: hclose x, hclose[x]

Where x is a file or process handle, closes communication to it and destroys the handle. (The corresponding integer can no longer be applied to an argument.)

q)h:hopen `::5001
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 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; 

Before V3.6 2019.09.19

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