Документ взят из кэша поисковой машины. Адрес оригинального документа : http://www.atnf.csiro.au/pub/people/vlbi/s2/ver3.2b/rclco/rcl/1readme Дата изменения: Fri Sep 4 13:46:46 1998 Дата индексирования: Tue Jun 29 00:51:29 2010 Кодировка: Поисковые слова: arp 220

RCL Interface Library Routines
------------------------------

These routines are for use by software which controls devices using the
RCL interface (RCL = Radioastronomy Control Link, also called Recorder
Control Link). This software runs on an external computer, such as the station
control computer at a radio-telescope installation or the correlator control
computer at a data processing center. RCL connections can be made with
serial cables, or over an Ethernet link by means of internet sockets.

Different types of RCL devices are supported which can have different
command sets, except for a small number of "generic" commands which must
be implemented by all devices. The front-end interface functions for RCL
commands are found in the source files rcl_cmd.c, rcmd_s2rtpt.c, and
rcmd_s2das.c. (Each of these also has a corresponding .h file).
The functions in rcl_cmd.c are generic RCL commands or commands which apply
to more than one type of device. The functions in rcmd_s2rtpt.c are
specific to S2 recorders (S2-RT or S2-PT) and the functions in
rcmd_s2das.c are specific to S2 Data Acquisition Systems (S2-DAS).
The RCL library ensures that commands from a particular command set
get sent only to the right type of RCL device by checking the device
identity string from the IDENT command (rcl_ident()). See the definition
of the global variable RclDevIdent in rcl_def.h for more information.

Error codes and status codes may be defined differently by different
RCL device types, so always be sure to interpret such codes in the context
of the particular device which returned them. The safest way to handle
error and status codes is to translate them to text messages using the
functions rcl_error_decode(), rcl_status_detail(), or rcl_status_decode()
(see User Notes below).

The current version of these routines works on IBM PC compatibles under DOS
compiled with Borland C++, or under Unix compiled with GNU C (tested
under SunOS 4.1.3, Solaris 2.5, Linux 1.2.12, and Linux RedHat 2.0.31).
The DOS version works only with serial ports, and the Unix version works
only with network connections. The main difference is that the DOS version
uses the rcl_syss.c module, while the Unix version uses rcl_sysn.c. Other small
differences are handled with #ifdef DOS or #ifdef UNIX in the code.
For Linux systems the macro LINUX is #defined in addition to UNIX. Some
effort may be needed to port this library to other platforms, but most
necessary changes should be isolated to the rcl_sys*.c routines.

Compiling
---------
First you should decide which types of RCL devices you want to support by
editing the macros RCL_SUPPORT_* in the rcl_def.h file. For each type of
RCL device use #define to include support or #undef to remove support.
The default behaviour is to support all existing RCL device types.

Now you are ready to compile. Different makefiles are provided to compile
the source files on different systems as follows:

To compile under SunOS 4.x: make -f makefile.sun
To compile under Solaris: make -f makefile.sol
To compile under Linux: make -f makefile.lnx
To compile under DOS: make -f makefile.dos

Or copy the appropriate file to 'makefile' and then just type 'make'.
You'll probably get some warnings, this is OK. Note that compilation
results in four separate object files, not a true library archive. If you
want you can combine the objects into a library as appropriate for your
particular computer system. If you have problems with long file names
under DOS then truncate all names to 8 characters (not counting the up
to 3-character extension).


Source files
------------
rcl_cmd.c -Generic RCL command interface routines. Uses #include to include
additional device-specific routines in rcmd_s2rtpt.c
and rcmd_s2das.c.
rcl_pkt.c -low-level RCL packet assembly/disassembly
rcl_syss.c -system-dependent serial port interface routines
rcl_sysn.c -system-dependent network interface routines
rcl_util.c -misc utility routines that may be useful for user software.
test.c -A small test program demonstrating how to initialize the RCL
and send one command.

User software communicates with the RCL interface library by calling the
functions listed in rcl_cmd*.h (not including the general message formatting
routines rcl_general_cmd() and rcl_simple_cmd()). Each function
corresponds to an RCL command. Before starting, the rcl_init() procedure
from rcl_pkt.c must be called, and after finishing, the rcl_shutdown()
procedure should be called. When using network RCL connections, the rcl_open()
and rcl_close() routines in rcl_sysn.c should be called to open and close
connections. The "reference address" returned from rcl_open() is used in
place of the RCL address to refer to a particular network connection.

An example program that uses the RCL interface library is called RCLCO. It
can be used to exercise and test all RCL functions of the S2 recorder
or S2 Data Acquisition System both under DOS (serial ports) and Unix/Linux
(network sockets). The rcl_sys*.c files as supplied are ready for use with
the RCLCO program, which is located one directory level up.

For more information refer to the S2-RT or S2-PT User's Manual, Appendix A,
"S2 RCL Serial Communications Protocol".
If you have any problems or questions please contact CRESTech/SGL S2 support by
Internet email to: s2support@sgl.crestech.ca
For information on the World Wide Web see: http://www.sgl.crestech.ca/

Good Luck,

Georg Feil
Last updated 98/07/23

-----------------------------------
User Notes:

A) Error Messages
The rcl_error_decode() function of the RCL Interface Library can be used
to decode negative numeric error codes returned by the functions in
rcl_cmd*.c, giving a text message for display or logging purposes.
Different RCL device types may have different definitions for the same
error codes, so be careful to decode the error using the same device
which returned it. Note that "local" errors which arise before commands
even reach the RCL device have positive numeric codes and cannot be decoded
with rcl_error_decode() (these local errors are defined in rcl_def.h and can
be decoded using rcl_error_decode_local()).

B) Status Messages
A similar issue (converting numeric codes to text) exists for status requests
made by rcl_status(). The preferred command to "decode" the numeric codes
from rcl_status() is rcl_status_detail(). Although rcl_status_decode()
also exists, the rcl_status_detail() command is preferred because the
text for status codes can contain occurrence-specific information.
The text obtained by rcl_status_decode() only includes the "generic" part
of the status message. In contrast error messages are simpler because
their text never changes (i.e. is always generic).
Note that two versions of the status command (rcl_status() and
rcl_status_detail()) are provided only for efficiency so that you
can use the "fast" one for polling and the slower one (rcl_status_detail())
after problems are found if you need the text messages. If you always
ask for the text messages regardless, you can skip calling rcl_status() and
call rcl_status_detail() directly with the 'reread' parameter TRUE.
See comments in rcl_cmd.c for more info.

C) Command Response Times
The _typical_ response time when calling functions in rcl_cmd.c
varies depending on the command, but will be less than the "timer
duration" value given in the RCL spec (S2 User's Manual appendix A).
The _maximum_ response time is 3 times the timer duration value since
up to 2 retries are automatically performed for most commands.
(Note: The number of retries is given by the RCL_RETRIES macro but this
should not normally be changed.)
The following commands are special and will not be retried, so their
maximum response time is the timer duration value:
rcl_ping()
rcl_time_set()
rcl_time_read()
rcl_time_read_pb()
rcl_align_abs()
Users should perform retries for these commands as needed. The above list
is based on condition checks in rcl_general_cmd().


Local CRESTech note:

-The file rcl.h is a hard link to the same file in /home/s2/ros/src/ros.
Don't edit it with the PC version of vi, as it seems to delete first, which
ends up creating a distinct file.