Command: open

Syntax

open <channel> {,<mode>}

Description

Open a system input/output channel for communication. This includes opening communication channels to Fire translator Services (i.e. not database services) running on a web server.

Parameters

• <channel>
  A channel identifier. If the identifier does not exist, it will be created using current scope rules. If it is unassigned, it will be given the value of the next free system channel.

• <mode>
  One of the following values:

• r
  Channel to be opened in read-only mode.

• w
  Channel to be opened in write-only mode.

• rw
  Channel to be opened in read/write mode.

• a
  Channel to be opened in write-only append mode.

If omitted, r is assumed.

Mode a is valid only for text file channels.

Switches

• -at=<atable>
  An atable to be searched within callback procedures for this channel. This means that any identifiers within <atable> referenced in a callback do not have to be prefixed by ~<atable>. This cannot be the local atable.

• -bin
  Open the socket channel (see -ip) in binary listening mode. The default mode is text mode. This switch is only used for socket channels.

• -c
  If <channel> is already open, get confirmation from the operator before it is closed and reopened. If the file to be written (w mode) already exists, get confirmation before it is overwritten.

• -del=<string>
  Use <string> as the delimiting character(s) between fields when reading from or writing to the channel. For read channels, <string> may be a one or two character string, containing a delimiting character and optionally a space to indicate that white space is also permitted. For write channels, <string> may be any sequence of characters. If no delimiter is set for a channel, then ', ' (command and/or space) is used when reading from the channel, and a space is used when writing to the channel.

• -f=<file>
  The name of a text file to be opened on <channel>.

• -if=<file>
  Equivalent to -f=<file>,r

• -ip=<string>
  The name of a host and port number to open a communications channel to. The process to which the socket is connected must communicate in text packets, each terminated with a \n character. The value of the parameter should be a string value indicating a host IP address or name and a port number, in the form host:n. The socket must be a STREAM (TCP/IP) socket. Once open, the channel can be switched from a text channel to a binary channel with the ability to receive asynchronous Fire Hose protocol events similar to listening channels (see -li).

• -li=<port>
  Listen for a connection on a port number. When a caller connects, the channel is available for binary communication from the caller using the Fire Hose protocol. The socket will be a STREAM (TCP/IP) socket. Events received on the channel are processed asynchronously. Passing a <port> of 0 will grab a free one. The port grabbed can be subsequently accessed via the channel.name attribute.

• -of=<file>
  Equivalent to -f=<file>,w

• -p=<string>
  The name of an external process to be opened on <channel>.

• -peer=<host>:<port>
  The network_socket of a peer Fire process (already open) to which a communication channel should be opened. Once the channel has been opened, commands can be sent to the peer for execution, via channel.command and channel.evaluate.

• -raw
  Ignore continuation lines. Without this switch, lines ending in a \ character are assumed to merge with the next line into a single line. The presence of this switch will result in \ characters at the end of lines being treated as normal characters, and consequently lines will not be merged.

• -req=<string>
  The url of a remote eim data transfer service running on a web server.

• -s=<string>
  The name of an external data transfer server process to be opened on <channel>. This will then run in eim client/server mode.

• -syn
  Mark the channel as synchronous. Only binary channels have this facility whereby during execution of events received on this channel other synchronous channels are prevented from receiving events until the first event has been processed. The default behavior is for binary listening channels to be not synchronous.

• -tim=<num>
  A timeout, in seconds, to wait for a connection to and subsequent responses from a server process or communications socket. If not specified, the timeout is 60 seconds. A value of 0 indicates no timeout, i.e. blocking reads, and is not advised.

• -uof=<string>
  The name of an external filter process to be opened on <channel>.

Notes

The system numeric free_channel may be used to request an unused channel number.

The <mode> parameter is ignored for both data transfer server and filter process channels, which always use w.

Examples

Open a file for reading.

open chan1,-f=test.dat

Open a file for writing.

open chan2, w, -f=outs

Open a process for reading on the next free channel.

channel myc
open myc, -p='ls -l'

Open a server process on the next free channel.

open myc, -s='dxf_server'

Open a connection to a socket.

open myc,-ip='manta:4999'

Open a connection to a Translation Service running on a Web Server.

open ch,-req='http://www.my_web_server.com/xmarc/Broker?service=ACAD_SERVICE'

Open a listener connection.

open myc, -li=3101

Open a channel to a peer process.

# Start another fire process
numeric port=free_port
string prog = flocal('$MXBIN/'|program)
:^(prog) -netsock=^(port) &

# Open a channel to it
open myc, -peer='localhost:'|ns(port), -tim=10

See Also