Skip to content

hopen, hclose

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

KDB-X communicates with the file system and other processes in two ways:

  • One-shot functions
  • Handles to persistent connections

hopen opens connections and hclose closes them.

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
  • communicationhandle is a symbol atom or string
  • timeout is a number of milliseconds as a long atom
  • port is a local port number as a long 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 `:tcps://mydb.us.com:5010             / SSL/TLS with hostname
hopen(":10.43.23.198:5010";10000)           / IP address and timeout
hopen 5010                                  / local port number

The timeout and the port number must be longs: hopen 5010i signals a 'type error.

For interprocess communication (IPC) compatibility, hopen serializes as the lambda {hopen x}. It accepts any of these arguments:

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

Files

If filehandle specifies a file path that doesn’t exist, hopen creates it, including any directories.

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

Passing strings instead of symbols avoids interning them.

This is useful when you embed 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, apply the handle to the data, as you do for IPC:

q)r:hdat 0x2324
q)r:htxt "some text\n"
q)r:htxt ` sv("asdf";"qwer")
q)hclose each (hdat;htxt);
q)read1`:sub/dir/f.dat
0x2324
q)read0`:test.txt
"some text"
"asdf"
"qwer"

Processes

Communication handles

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

TCP
`:host:port[:user:password]
host can be a hostname or IP address; if omitted, it defaults to localhost
Unix domain socket
`:unix://port[:user:password]
Unix domain sockets can have significantly lower latency and higher throughput than a localhost TCP connection
SSL/TLS
`:tcps://host:port[:user:password]
TCP with SSL/TLS encryption
`:unixs://port
Unix domain socket with SSL/TLS encryption
See SSL/TLS.
FIFO/named pipe
`:fifo://filename
Unix only
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

If the server session was started with the -u or -U command-line option, you must supply a user and password. The server passes them 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:

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

To send HTTP or HTTPS requests, for example to REST APIs and cloud services, use the Kurl module.

One-shot request

To run only one synchronous query, use a one-shot request: it connects, sends the query, gets the result, then disconnects.

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

It is more efficient to keep a connection open if you can reuse it for other queries.

To set a timeout for a one-shot query, use `::[(":host:port";timeout);query]:

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

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

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. You can no longer apply the corresponding integer to an argument: doing so signals an error such as 'Cannot write to handle 3. OS reports: Bad file descriptor.

q)h:hopen ":test.txt"
q)h "first line\n";
q)hclose h
q)@[h;"second line\n";{"error: handle is closed"}]
"error: handle is closed"

When you close an asynchronous connection, hclose doesn't send pending data on the connection handle. If you need the data sent, flush the handle explicitly before closing it:

neg[h][];hclose h;

.Q.Xf (create file)

Communication handle, Connection handle, File system, Interprocess communication

SSL/TLS, Kurl module

Q for Mortals §11.8.2 Opening a Connection Handle