Interface --------- The interface section is responsible for communications between Poco and other programs. The primary standards used for communication are the KTL keyword system and the music library. This results in the interface tracking the status of each KTL keyword and deciding when to send updates to interested processes. The interface also needs to keep track of existing connections and create new connections if required. The KTL standard is well defined elsewhere, but here are some of the details. Each KTL keyword is defined in a central database and each has a type of integer, floating point, or string. A KTL server takes requests from KTL clients (Poco is a KTL server). These requests can be for status or change. A status request simply asks for an update of a keyword's value, which the serve supplies as soon as possible. A change request asks to change the value of a keyword to a new value and asks for verification on completion. Change requests often act as commands to Poco. Multiple processes can request conflicting commands in which case the server must tell the clients if their requests succeeded or failed. Request verification comes in two parts. All requests receive an initial response indicating that the request was received and it was understood, or that the request was not understood. The second part of the status request response is the value of the keyword. The second part of a change request response indicates whether the change succeeded or failed. The KTL standard also specifies that keyword changes be broadcast to all clients of the server. These updates have a maximum update rate to avoid flooding the network. For most keywords this is once a second. The interface is implemented in a few classes, the most important being CInterface. CInterface is responsible for tracking KTL keyword values and states, informing the Telescope and Control sections when changes are requested by other programs, and informing other programs when keyword values change due to actions taken by Poco. The primary piece of CInterface runs in the central thread and can easily communicate with the Telescope and Control objects, which also run in the central thread. All of the actual socket connection and listening sockets are created by threads that CInterface creates. These threads contain all actions that might cause the central thread to block for more then a tiny fraction of a second. This includes opening new sockets, reading and writing to existing sockets, and accepting socket connections. The primary connection, at this stage, is to traffic. This connection is made with the CTrafficConThread and CTrafReadT classes. These classes are based on the CDuplexFileT and CDuplexReadT classes. The CTrafficConThread, and CTrafReadT know the structure of the basic music messages and convert them to and from a form that CInterface understands. The CTrafficConThread thread is responsible for opening the traffic connection. CInterface keeps track of each KTL keyword. For each keyword, it tracks the keyword's value, the last time the value was changed, the last time the value was broadcast, and a list of clients that are waiting for confirmation or failure of a keyword change. Each keyword also needs functions defined that handle what actions Poco should take when its value is changed, as well as functions that determine if an action succeeded or failed. To keep this as flexible and as fast as possible, pointers to static member functions are used. These functions, called action functions, are defined within CInterface. All start with the prefix af and each takes the same list of arguments: pointer to the key to change, pointer to CInterface, and the ConnectionID. The ConnectionID indicates which client is requesting the change. The action function to use with each keyword is defined in CInterface::setupKTLKeyWords() function. For speedy and convenient access, each keyword is specified by a specific CInterface member variable (ex. m_pPOCRAA), each keyword can be referenced from the m_KTLKeyList, and each keyword is also placed in the m_pKTLKeyArray. The specific keyword variable makes it easy for the Poco program itself to specify a variable. The list makes it easy to perform an action on every keyword (like broadcasting, or deleting), while the array is sorted by the KTL keyword id numbers making for fast lookups for client requests. The actual keyword, a CKTLKeyWord object, is created dynamically and all these other variables are pointers to the single keyword object. Each keyword object is created and defined by CInterface::KTLSetupFunction, which guarantees that each keyword is valid and that each keyword is added to the list. All of this occurs in the CInterface::setupKTLKeyWords() function that also builds the array of KTL keywords. For reliable communication the KTL standard has some shortcomings. It makes no provisions for multiple related keywords to be sent as a single block. For example, the telescope position is stored across several different keywords. This include actual hour angle, actual declination, actual right ascension for each set of coordinate systems (mechanical, observed, apparent, and mean). Some programs could get very confused if they mix newly arrived keyword values with out of date values that are still floating around. To get around this shortcoming, Poco always sends out all position keywords followed by a time stamp (keyword POCPTIME). It also always tries to send all the position keywords out as a single broadcast message. A list of all KTL keywords in use on Poco and a brief description for each can be found at