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

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

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

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

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