Each server in your server list has a state that it is in.

The valid states are:

Servers are not automatically connected to when you add them to the server list. Instead, they are in the RECONNECT state which is quiescent. Whenever you attach any window to the server when it is in the RECONNECT state, it will automatically come up.

Connection to a server is a complicated concept. It involves the whole action from when a server has a window and is in RECONNECT, until either the server reaches SYNCING or CLOSED with no more addresses.

When a server with a window is in RECONNECT, it switches to DNS and looks up the addresses for its hostname. This returns one or more addresses. For each of the addresses returned, the server switches to CONNECTING and continues on until either it reaches SYNCING or CLOSED for that address.

If SYNCING is reached, the server throws away any remaining addresses. If CLOSED is reached, the client advances to the next address and goes back to CONNECTING. This continues until either SYNCING is reached or CLOSED is reached and there are no more addresses left to try.

All of the above is to be considered a single “connection attempt”, and although all of the above actions are nonblocking and asynchronous, until one of the two terminal conditions are reached, the client cannot be thwarted.

Terminal condition one, success:

  on server_state "% % SYNCING" {
     xecho -b Server $0 has been accepted onto irc.
  }

Terminal condition two, failure:

  on server_state "% % CLOSED" {
     if (serverctl(GET $0 ADDRSLEFT) == 0) {
         xecho -b Server $0 could not connect to irc.  Help me!
     }
  }

Remember, CLOSED is not a terminal condition unless ADDRSLEFT is also 0!

You, the user, have the ability to terminate a connection to a particular address by using disconnect. See the help files for disconnect and reconnect for important distinctions between the two.

If we are accepted onto irc, then the connection stays open until either the server rejects us (closes our connection) or we reject the server (due to a network error). When the connection is severed, the server goes into either EOF or ERROR state to tell you who is closing, and then to the CLOSING state, and finally the CLOSED state.

Once a server is in the CLOSED state and there are no more addresses left to use (either because we have tried them all, or because we reached the SYNCING state), it cannot be used again until it is reset to the RECONNECT state.

You can put a server in the RECONNECT state with

1. reconnect refnum
2. server +refnum
3. window server refnum

The reconnect_script implements epic4 behavior of automatic reconnecting to servers when you are disconnected. Ordinarily the above technical information is not interesting to the user, but only to those who need to implement their own scripted reconnection scripts.

An on server_status event is thrown whenever the status of a server changes.

The $serverctl(GET refnum STATUS) function can be used to query the current state of the server.

Server states are an EPIC5 feature which were invented during the nonblocking connection project. They have been expanded during the nonblocking dns project, the nonblocking ssl project, and the reconnect script project.