

 SampLin 1.5.0                                      Samuel Kvasnica
                                                        15.12.1999


     This file contains brief installation, compilation and usage
     instructions for SampLin version 1.5.0. This is the only
     documentation at the moment. Features marked as (*) are still
     under development.

     SampLin Home Page is located at sites:

     http://www.iaee.tuwien.ac.at/sensor/samplin
     http://www.troja.mff.cuni.cz/~kvasnica/samplin.html  (not updated
     regulary)

     For comments, bug reports and questions contact me at e-mail
     address: kvasnica@iaee.tuwien.ac.at. Please read this file as well
     as BUGS, FAQ and TODO files (and try to find out the problem
     yourself in source code) before contacting me. In case of
     segfault, configure with debug option (--enable-debug), compile
     again and try to debug core dump after crash. Use `ulimit -c
     unlimited' to get core dump in bash.

     All new features/changes/improvements are logged in file NEWS.


 CONTENTS


     0. Introduction
     1. Compilation
     2. Installation
     3.  Usage

          3.0 Compatibility
          3.1 Running SampLin
          3.2 Configuring devices
          3.3 Remote devices, network support
          3.4 Script programming
          3.5 Script commands

     4 Device drivers
     5 Acknowledgments


 0. INTRODUCTION


     SampLin is Scientific Data Acquisition, Visualization and Process
     Control software for Linux and other unix platforms.

     History of  SampLin began in september'97. There has been a mass
     spectrometer, optical multichannel spectograph and few other
     devices for plasma diagnostics in our plasma lab at TU-WIEN. Each
     device has had it's own 286, it's own (and mostly very ugly)
     software with it's own mysterios data formats. There has been a
     big demand on centralization of device control and data
     acquisition on single computer using the same software and common
     data format. Usage of stable software running stable OS was also a
     very important requirement. I didn't find anything really suitable
     and usable - well, except GNU C compiler and Linux.

     We needed software to control variety of devices connected via
     serial, GPIB ports or Lab cards; to process, display and
     load/save/print acquired data. This software had to be really
     universal to enable to connect devices with very different control
     algorithms, data formats and data processing. It was desired to
     control more devices simultaneously using one computer. Remote
     control over TCP/IP was also desired.

     SampLin has been build around script language originally based on
     YABASIC and Qt tool kit. The script language implements default
     BASIC commands, commands for creating and maintaining dialog
     windows with widgets and commands for easy data transfer and
     visualization. SampLin's script language is not directly
     interpreted but precompiled before execution. So it's fast enough
     for most tasks. Currently the script language started to evolve
     into a kind of C-like language
     but it is still possible (with minor changes) to use old BASIC
     syntax so that everybody should be able to write a script even
     without having much praxis in programming.

     I don't claim SampLin currently flawlessly solves all problems
     mentioned above. But it tries to. It has been proved to be very
     useful and reliable in our lab. There are many new features to add
     and many old features to tune up. To write versatile and reliable
     software it's important to test it in variety of environments and
     with variety of devices. That's why I need your feedback and help.

     SampLin is distributed under the terms of GPL. For copyright
     details see file COPYING. I'd appreciate a short E-mail message or
     acknowledgement in case you found SampLin really useful.


 COMPILATION


     To compile SampLin you'll need Linux >=2.0, libc6, gcc > 2.8.x or
     egcs, X11R6 >=3.3 (multithreaded !), Qt > 1.40 (www.troll.no), KDE
     >= 1.0 libs (www.kde.org) and drivers from Linux gpib library
     package (www.llp.fu-berlin.de).
     SampLin is MULTITHREADED (well, at least SampLinExec), so be sure
     you use libc6 and libraries compiled as multithreaded with
     -DREENTRANT (especially X11 and Qt libraries). RedHat >=5.2 should
     be o.k. Enclosed PCL card drivers (directory src/drivers) will
     compile only with 2.0.x kernels. SampLin should run also other
     unix systems but has been tested only on Linux so far. The
     essential porting problem would be the drivers from gpib library
     which support only linux.

     Since version 1.2 SampLin doesn't use the gpib library, it
     communicates directly with gpib drivers. That means, you have just
     to install the gpib drivers if you need GPIB support. If you don't
     need GPIB support, you don't need anything from gpib library
     package.

     If you'd like to play around with script language grammar you'll
     also need flex++ and bison++ (flex and bison won't work). Flex++
     and Bison++ generated .cpp files are included so normally you
     won't need flex++ and bison++.

     Download the SampLin package SampLin-x.y.z.tar.gz/ (x.y.z stands
     for version number). Unpack the package using `tar -zxf' or
     `gunzip; tar -xf' commands.

     `cd SampLin'

     Read the `INSTALL' file for installation instructions. Start the
     configure script (use --help to see
     possible options):

     `./configure'

     or

     `./configure --enable-debug' to compile with debug info

     or

     `./configure --enable-drivers' to compile drivers in src/drivers
     directory
     (WARNING: works only woth 2.0.x kernels)


     And build SampLin:

     `make'


 2. INSTALLATION


     To install SampLin you need just to type:

     `make install'

     SampLin will be installed by default under $KDEDIR. SampLin item
     will be added into KPanel start menu. Use --with-install-root=
     option to specify different root directory at configure time.

     Following executables will be installed:

     SampLin - User interface (UI). Use this to edit/run/trace your
     scripts
     SampLinExec - Script executor. Use this to run scripts
     SampLinDevices -  Device configurator
     SampLin Graph - Standalone graph widget to view/edit your graphs

     If you'd like to look at sample scripts and sample graph data,
     copy the directories $KDEDIR/share/apps/SampLin/examples/Data and
     $KDEDIR/share/apps/SampLin/examples/Scripts to $HOME/SampLin.
     Script file `widgets.Script' demonstrates usage of various
     widgets, `flow.Script' is script to control MKS flow controllers
     using Advantech PCL818 and PCL727 cards, `qms.Script' controls
     BALZERS QMG420 quadrupole mass spectrometer over serial port.

     Driver modules for PCL Lab cards can be found under
     $KDEDIR/share/apps/SampLin/modules. Remote server executables are
     in $KDEDIR/share/apps/SampLin/remote.


 3. USAGE


 3.0 Compatibility


     SampLin graph and device configuration files are only forward
     compatible. It means SampLin 1.3.1 files are not readable by
     SampLin version < 1.3 However you can use SampLin 1.3.1 to open
     old files, they'll be automatically converted to new format during
     save operation. Version 1.3 has a bit different script syntax, so
     you'll have to change your 1.2 script files a bit. Version 1.5 has
     got also a new grammar, see below.


 3.1 Running SampLin


     SampLin [script file]

     After invoking SampLin, user interface (UI) appears. User
     interface consists of Menu bar, Toobox, Editor window, Message
     window and a Status bar. If running the first time SampLin creates
     the directories $HOME/SampLin/Data, $HOME/SampLin/Scripts and
     config file $HOME/kde/share/config/SampLinrc.

     Use menu items File/New,Open,Save,SaveAs to create new, open
     existing, or save script. (By default in directory
     $HOME/SampLin/Scripts.)  Use Script/Run, Stop,Step,Goto,Reset to
     run, stop, step one line, go to line at cursor or reset (stop and
     initialize) current script.

     SampLin UI forks separate process SampLinExec to run/trace the
     scripts.

     Samplin may be invoked with script name as parameter. This file
     will be opened in editor window. If the full path doesn't exit, it
     will look for it in your $HOME/SampLin/Data directory.

     Configuration/SampLin... opens dialog with program and script
     language options.

     Section PATHS contains edit fields for SampLin root directory name
     and it's subdirectory names where SampLin looks for scripts and
     data by default. Edit field `Devices file' contains the name of
     the file where SampLin stores device configuration. `Interpreter'
     contains name of the interpreter to be used, SampLinExec is the
     default.
     Section Interpreter contains following options:

     Infolevels sets the level of interpreter messages

          Error    - report only severe errors that disable to
          continue the execution

          Warning    - report also warnings such as `Unable to
          open device' etc.

          Note    - report more details about program parsing and
          execution, i/o operations

          Diagnostic    - report everything: parsing/compilation
          details, useful for interpreter diagnostics

     Output/Messages selects output destination for interpreter
     messages and print output. `Window' sends messages to SampLin UI
     message window, `stdout/stderr' prints messages to the terminal
     from which was SampLin invoked.

     Option 'include timestamp' reports actual time along with
     interpreter messages. Options 'autosave' saves automatically any
     script changes before compilation.

     Menu item Configuration/Devices... forks SampLinDevices device
     configurator. See section 3.2 for details.

     For all frequently used menu commands there are appropriate
     buttons located on toolbar.

     It is possible to run scripts using 'SampLinExec scriptname'
     directly, without starting user interface.


 3.2 Configuring devices


     Menu item Configuration/Devices... has the same effect as invoking
     device configurator 'SampLinDevices' from shell.  New,Copy, Rename
     and Delete buttons located at bottom are used to create new, copy,
     rename or delete device selected in the list box.The name of the
     device entered when creating new, copying or renaming device will
     be used later to control it from within the script language.It's
     necessary to define device parameters for new device in Path,
     Common options, Serial options and GPIB options section of the
     dialog.

     Path section

     Field `Path' contains device path - e.g. /dev/ttyS0 for first
     serial port, /dev/gpib0/master for first linux-gpib card etc.
     DON'T PUT GPIB-LIB DEVICE NAME IN THIS FIELD ANYMORE, SAMPLIN USES
     GPIB DRIVERS DIRECTLY. YOU EITHER DON'T NEED TO CONFIGURE GPIB
     DEVICES IN /etc/gpib.conf. In case of remote device place the host
     name into the `Host' edit field. Type in some description of the
     device into the `Title' field (optional).

     Common options

     Three type of devices can be defined: GPIB, Serial or Void (e.g.
     Lab cards). Select appropriate type from combo box `type'. In case
     of serial/GPIB device fill out also the Serial options / GPIB
     options section of dialog. Select big or little endian option from
     `Endian' combo. (Usually little for Intel based devices and big
     for Motorola based devices). Click `Read enable' `Write enable' to
     enable reading or/and writing from/to the device. Fill in default
     delay in microseconds after device write in `Delay' field. Put
     default timeout for remote devices in seconds into the `Net
     timeout' field. (*) Type in hexadecimal code of the `end of
     string' character into the `EOS' field. This will be used to
     terminate all strings written in ASCII mode (e.g. DEVWRITE device,
     A$) as well as EOS stop character when reading ASCII data. Typical
     settings are 0x0d for \r (CR, carriage return), 0x0a for \n (LF,
     linefeed) or 0x0d0a for \r\n (CRLF dos-like combination). 2 byte
     setting (e.g. 0x0d0a) works should work with serial and void
     devices, support in GPIB mode depends on used device driver.

     Serial options

     Select `Baud rate', `Data bits', `Stop bits' and `Parity' for
     serial device.

     GPIB options

     Type in GPIB bus address of the device into the `GPIB address'
     fields.
     Check `Bus master device' for bus controllers ( ! you won't do
     this normally !  ).
     Device configuration is stored in file Samplin.devices located in
     $HOME/.kde/share/apps/SampLin


 3.3 Remote devices, network support


     For remote devices fill in the host name where device is connected
     into the `Host' field as mentioned in section 3.2 Path. Nothing
     else is needed to configure on client side. Since SampLin remote
     features use the RPC to communicate with server, you need the RPC
     portmapper running on both client and server side. For GPIB
     devices you'll need to run rgpib_svc executable
     ($KDEDIR/share/apps/SampLin/remote/rgpib_svc) on your server. For
     serial or void devices you need to run the rdevice_svc executable
     found also in `remote' subdirectory. They must be run as root in
     order to register RPC service. rdevice_svc allocates service
     number 0x20004321, rgpib_svc number 0x20004322. Invoking
     rdevice_svc or rgpib_svc with `--debug' option will cause them to
     print all requests and device operations on console. Device
     permissions file /etc/rdevice.conf is needed in order to enable
     access to serial and void devices from remote host. Sample
     rdevice.conf file is included in this `Doc' directory. It contains
     one line per device, each line contains device path, `:' colon
     separator and comma separated host list (addresses or IP numbers).
     File /tmp/rdevice.status shows opened devices along with hosts
     name, uid, gid, fd and flags. Note that rdevice server is limited
     by maximum opened files per process which is usually 255. There's
     NO rgpib_svc authentication by now, sorry. DON'T use rgpib_svc
     from linux-gpib library package with SampLin, it won't work (not
     only because it uses different service number).


 3.4 Script programming


     SampLin script language was originally based on YABASIC which uses
     a superset of standard BASIC commands.
     (All Win95 features as well as graphics features have been
     removed.) Script language is currently evolving into a
     C-like syntax, but it is still possible to programm in a BASIC-way
     with some minor changes to make script programming
     easy for newbies. Some description of YABASIC syntax can be found
     file yabasic.txt, any BASIC handbook should help as well. All
     commands, operators and keywords of script language are listed in
     section 3.5.

     Script grammar has been upgraded towards C-syntax in version
     1.5.0. You will have to make these changes to run your older
     scripts in version 1.5.0:

             * Conditional expression after IF _must_ be closed
               between parenthesis.  e.g. IF (a<0) THEN ...
             * Operator '=' means always an assignment, use
               operator '==' for comparison, e.g. IF (a==b) THEN
               ...
             * There must be a separator behind last command on
               the last line of file - a newline or ';', not an
               EOF
             * Use ',' instead of ';' to supress newline printing,
               ';' works as separator now ! e.g. print A$,v,B$,
             * INPUT works with stdin, use INPUTDLG for windowed
               input
             * Since version 1.3 all array operations use []
               brackets instead of (). It means DIM A[10], not DIM
               A(10).  Similary A[1]=A[2]+3. If passing array as
               argument square brackets are also required: DEVREAD
               QMS, A[], 10,1

     Using '=' in conditional expression will produce a warning
     It's also recommended to follow following rules when writing new
     scripts:

             * Use rather '// comment' and '/* comment */' than
               '#' or REM for comments
             * Use rather ';' than ':' or newline as statement
               separator (well, newline is still accepted as
               separator but it is not very smart)

     Since version 1.5.0, following C-like syntax can be used:

             * if (expression) {statement_list} else
               {statement_list}
             * while (expression) {statement_list}
             * do {statement_list} while(expression)
             * for (assignment; expression; assignment)
               {statement_list}
             * chained assignments: a=b=1;
             * new operators:
               ++,--,//,**,^^,||,&&,<<,>>,&&,||,~~,!,&=,|=,~=,
               e.g.: ++a; a++; a-=1;
             * conditional expression return a value, e.g. a=b>2
               sets a to 1 if b>2 or 0 if b<=2

     Next section contains list of all script language commands.
     However only SampLin specific commands are described particularly.

     To communicate with devices, device names defined in device
     configuration dialog (section 3.2) are used.


 3.5 Script commands


     /* comment */, // comment - use these for comments
     if (expression) {statement_list} else {statement_list} - if
     condition
     while (expression) {statement_list} - while loop
     do {statement_list} while(expression) - do/while loop
     for (assignment; expression; assignment) {statement_list} - for
     cycle
     ';' - command separator, should be used instead of ':' which is
     obsolete
     REM, `#' - comment; obsolete, don't use these anymore
     FOR, TO, STEP, NEXT - cycle FOR i = 1 to 10 STEP 2: ... : NEXT i
     GOTO label - jump to label
     GOSUB - call subroutine label
     ON num GOSUB label1, label2... - call subroutine depending on
     value of num
     LABEL label - label of subroutine
     RETURN - return from subroutine
     END - end of program
     IF,THEN,ELSE,ENDIF (or just FI) - condition
     OPEN,CLOSE - open, close file
     PRINT - print string, value, place extra ',' at end to suppress
     printing of new line character
     DIM - dim an array, e.g. DIM A[10] or DIM A$[100]
     DATA - define data
     READ - read from data
     RESTORE [label] - restore to pointer to beginning of data at label

     WAIT num, PAUSE num - make pause of num seconds, use for long
     delays SLEEP num - sleep for num milliseconds, use for short
     delays only !
     BELL, BEEP - make sound
     AND, OR, NOT or &&, ||, !, ~~, - logical binary operators
     &=,|=,~= - logical unary operators
     &, |, ~ - binary operators AND, OR, XOR
     <<,>> - shift binary left or right (bitwise)
     ++,--,//,**,+=,-=,/=,*=,^=,<<=,>>= - unary operators
     <,>,!=,<>,<=,>=,== - comparisons (<> and != is the same)
     SIN(), ASIN(), COS(), ACOS(), TAN(), ATAN(), EXP(), LOG(), SQRT(),
     ABS(), SGN() - math functions
     INT() - return integer part of value
     FRAC() - return fraction part of value
     RAN() - random generator function
     LEFT$(),RIGHT$(), MID$() - string operators
     LEN() - return lenght of string
     VAL() - return string value
     STR$() - convert value to string
     CHR$() - convert ASCII value to string
     ASC() - convert string character to ASCII value

     DATE$ - contains current date
     TIME$ - contains current time

     TIMER ON|OFF - start or stop time; variable timer_sec will be
     incremented every second, timer_msec every millisecond. Note that
     with timer enabled program execution will become slower. That's
     because gettimeofday() is called after every program step. I have
     no idea how to make it better now.

     MESSAGE [type,] mesg$

          Shows a message dialog containing text mesg$ and Ok
          button. `Type' can be empty, INFO, WARNING or ERROR.

     INPUT [title] variable - Input string or value into `variable'.
     `Title' is string to be displayed as prompt.

     INPUTDLG [title] variable - the same as INPUT, but using an input
     dialog window. Current values of 'variable' will be displayed in
     input field

     CURSOR type - Change cursor icon for all active dialogs. 'Type' is
     DEFAULT for normal arrow icon or WAIT for clock icon

     DEVOPEN name - open device `name'

     DEVCLOSE name - close device `name'

     DEVREAD name, string$ [,len]

          Read ascii string$ from device `name', len is maximum
          lenght, EOS setting from device configuration will be
          used to find end of input

     DEVREAD name, array[], lenght, size

          Read binary data from device `name' to array[]. Array
          must be dimmed before as 1-dimensional array of values.
          `Lenght' is number of items to read. `Size' is size of
          items in bytes. If `size' is equal 0 then item size in 1
          bit. Order of read bytes when composing an item depends
          on little/big endian setting in device configuration
          dialog. Use negative value of size (with absolute value
          of item size) for signed conversion.

     DEVWRITE name, string$ [,len]

          Write ascii string$ to device `name', len is maximum
          lenght, EOS setting from device configuration will be
          used to
          terminate the string.

     DEVWRITE name, array[], lenght, bytes

          Write binary data to device `name' from array[]. Array
          must be dimmed before as 1-dimensional array of values.
          `Lenght' is the number of array items to write. `Bytes'
          is the number of bytes each array value is separated
          into before writing to device. Order of bytes written to
          device depends on little/big endian setting in device
          configuration dialog. Zero and negative value of `bytes'
          have similar meaning as DEVREAD parameter `size'.

     DEVCTL name, service, param

          Performs IOCTL call to device `name', integer number of
          service `service', integer parameter `param'
          Use &variable instead of 'param' to read back value
          returned from ioctl to variable

     DEVREADY(name)

          This function returns 1 if there are data available to
          read from device `name', otherwise returns 0. Useful
          when waiting for data on serial port.

     DEVSPOLL(name)

          Serial poll GPIB device `name'

     ADDGRAPH name$

          Open new graph window called name$

     DELGRAPH name$

          Close graph window called name$

     LOADGRAPH name$ [, file$]

          Load data into graph `name$' from file `file$'. If
          called without specifying `file$', file open dialog will
          be opened.

     SAVEGRAPH name$ [, file$]

          Save graph data, look LOADGRAPH

     EXPORTGRAPH name$ [, file$]

          Export graph data, look LOADGRAPH

     PRINTGRAPH name$

          Print graph name$

     SETGRAPHTITLE name$, title$

          Change graph name$'s title to title$

     SETGRAPHCOMMENT name$, position [, comment$]]

          Change graph name$'s comment to comment$, position in
          None, Bottom or Right; comment$ is optional

     SETGRAPHLEGEND name$, position

          Display graph name$'s legend, position in None, Bottom
          or Right

     SETGRAPHCOLORS name$, pcolor$, bcolor$

          Change graph name$'s plot area color to pcolor$ and
          background color to bcolor$

     ADDPLOT name$, plotname$

          Adds new empty plot series plotname$ to graph name$

     SETPLOTDATA name$, plotname$, arrayX[], arrayY[], [len]

          Sets plot series plotname$ data in the graph name$. X
          data are taken from 1-dim array `arrayX'. Y data are
          taken from 1-dim array `arrayY'. You can restrict data
          lenght using `len'

     SETPLOTDATA name$, plotname$, begin, step, arrayY[], [len]

          Sets plot series plotname$ data in the graph name$. X
          data begin at `begin', X axis step has a value of
          `step'. Y data are taken from 1-dim array `arrayY'. You
          can restrict data lenght using `len'

     SETPLOTDATA name$, plotname$, arrayX[], begin, step, [len]

          Sets plot series plotname$ data in the graph name$. Y
          data begin at `begin', Y axis step has a value of
          `step'. X data are taken from 1-dim array `arrayX'. You
          can restrict data lenght using `len'

     GETPLOTDATA name$, plotname$, arrayX[], arraY[]

          Get X and Y data from graph name$, series plotname$ to
          1-dim arrays arrayX, arrayY

     SETPLOTSTYLE name$, plotname$, style

          Change plot style, style = None, Line, Sticks, Dots or
          Spline

     SETPLOTPEN name$, plotname$, style, width, color$

          Change plot pen, style = None, Solid, Dash, Dot,
          Dash-dot or Dash-dot-dot; width is line width and color$
          is pen color

     SETPLOTSYMBOL name$, plotname$, style, width, size, fcolor$,
     lcolor$

          Change plot pen, style = None, Circle, Rectangle,
          Diamond, Triangle, DTriangle, UTriangle, LTriangle,
          RTriangle, Cross or XCross; width is symbol outline
          width, size is symbol size, fcolor$ is fillcolor and
          lcolor is outline color

     SETPLOTAXES name$, plotname$, axis1, axis2

          Assigns plot series plotname$ in graph name$ to X,Y axes
          axis1, axis2. Possible values for axis1 & axis2: Left,
          Right, Bottom, Top. Default setting is Bottom, Left.

     SETAXISTITLE name$, axis, title$

          Changes axis title for `axis' in graph name$ to title$.
          For `axis' values see SETPLOTAXES.

     SETAXISSTYLE name$, axis, style [,prec]

          Changes axis label style for `axis' in graph name$.
          Style is None, Scientific,General or Fixed. prec is
          optional precision.

     SETAXISSCALE AUTO [,ref [,minor]]

          Sets axis autoscaling feature on, ref is reference
          point, minor is max. number of minor tics (optional)

     SETAXISSCALE min,max,step [,ref [,minor]]

          Sets axis manual scale, min is minimum value, max
          maximum and step is major tic step (0 mean automatic);
          ref is reference point, minor is max. number of minor
          tics (optional)

     SETAXISFLAGS name$, axis, flag1 [,flag2 [,flag2 ...]]

          Sets axis flags, specify as many as desired of these:
          LOG (logaritmic), SYM (symmetric), INV (inverted), REF
          (include reference), FLT (floating)

     DELPLOT name$, plotname$

          Removes plot plotname$ from graph name$

     MULTI ON|OFF

          MULTI OFF disables receiving signals from dialog
          widgets. MULTI ON enables receiving signals again.
          Useful if communication with device may not be
          disturbed.

     PROGRESSDLG [text$ ,] step

          Call this with both parameters to initialize progress
          dialog. `Step' is total number of steps, text$ message
          to be displayed. Subsequent calls with one paramater
          `step' will update progress bar. Variable
          `progress_cancel' will be equal 1 is dialog was
          canceled, otherwise 0. Note that dialog will appear only
          if estimated total time (estimated during first step) is
          >3 sec.

     ADDDLG name, title$

          Creates new dialog called `name' with caption title$

     DELDLG name

          Deletes dialog called `name'

     SHOWDLG name

          Show dialog called `name'

     HIDEDLG name

          Hides dialog called `name'

     DLGACTIVE(dlg)

          Returns 1 if dialog `dlg' is active, otherwise 0

     ADDWIDGET name, type, x,y,w,h, ...

          Add widget into the dialog called `name'. Type may be
          one of: FRAME, TEXT, BUTTON, SWITCH, LCD, LED, SELECT.
          x,y,w,h are left top coordinates and width and height of
          widget. Widget specific parameters follow:
          FRAME ..., flags, width

               Draws a frame. `flags' specify frame type (0
               no frame, 1 box, 2 panel, 3 winpanel, 4 horiz.
               line, 5 vert. line + 0x10 plain, 0x20 raised,
               0x30 sunken ), `width' is width of frame in
               pixels

          INPUT ..., variable$

               Puts input field into dialog. Entered data
               will be stored into variable$

          TEXT ..., text$

               Puts text into dialog. text$ contains string
               to be displayed

          BUTTON ..., text$, label

               Places a push button into the dialog. text$
               contains button title, `label' is the
               subroutine label to be called upon button
               press

          SWITCH ..., text$, label, variable

               Places a switch (check box) into the dialog.
               text$ contains switch title, `label' is the
               subroutine label to be called when switch
               changes its state, switch state is stored into
               `variable' On = 1, Off = 0

          LED ..., variable, text$, color$

               Places a led diode into the panel. `variable'
               determines led state (0 light Off, <> 0 light
               On), text$ is led title, color$ led light
               color.

          LCD ..., prec, format , variable, color$

               Places an lcd display into the dialog. `prec'
               is the display precision (number of decimal
               places to be displayed), `format' selects
               format (0 decimal, 1 scientific, 2 octal, 3
               binary, 4 hexadecimal), `variable' is the
               variable to be displayed, color$ determines
               the color of lcd segments

          SELECT ..., array$[], variable

               Places an select widget (combo box) into the
               dialog. array$[] is a string array containing
               the labels to fill the select widget with.
               `Variable' is set to index of selected string
               from array$.

          GRAPH ..., name$

               Places graph widget into the dialog. name$ is
               name of the graph. Behavior is the same of the
               graph window.

          KNOB ..., from, to, step, variable

               Places potentiometer knob into the dialog.
               Range of the knob is defined by `from' and
               `to' values, step by `step' value. `variable'
               will contain current position (setting) of the
               knob.

          SLIDER ..., from, to, step, variable, scale

               Places slider control into the dialog. Similar
               as KNOB. For `scale' = 0, no scale will be
               displayed, for `scale' 1 resp. 2 scale will be
               displayed in the top resp. left or bottom
               resp. right position depending on widht/height
               ratio.

          LEVEL ..., scalewidth, from, to, color$, variable, scale

               Places level indicator into the dialog.
               `scalewidth' is width of scale in pixels to be
               drawn. For `scale' = 0, no scale will be
               displayed, for `scale' 1 resp. 2 scale will be
               displayed in the top resp. left or bottom
               resp. right position depending on widht/height
               ratio. color$ is indicator color.


 4. DEVICE DRIVERS


     There are 2 drivers for Advantech PCL-818 and PCL-727 cards
     included in $KDEDIR/share/apps/SampLin/modules directory. These
     drivers are experimental only. PCL-818 driver supports only
     autodetect configuration and A/D, D/A input/output by now. PCL-727
     supports only D/A output. Run `insmod devname.o' as root to insert
     driver to kernel. pcl818dev.tgz and pcl727dev.tgz contain device
     files to be created in /dev directory. Use `forceirq=IRQ' argument
     when running insmod pcl818.o to force driver to use interrupt IRQ.
     Use `base=ADDRESS' argument when running insmod pcl727.o to tell
     driver card base ADDRESS. I don't know why, but PCL818 card
     doesn't work with IRQ 6 in my computer. Driver for PCL812 card has
     been contributed by Dani Pardo and included in src/drivers/pcl812
     directory. I didn't test it by now since I don't have PCL812 card,
     but looks to be similar to PCL818.


 5. ACKNOWLEDGEMENTS


     I'd like to thank especially following people for their work:

        * Richard Stallman for the wonderful idea of GNU GPL
        * Linus Torvalds for starting Linux project (Without Linux I'd
          be probably still one of the slaves of Micro$oft)
        * Troll Tech team (www.troll.no) for writing Qt tookit and
          releasing free edition.
        * ? (ihm@kph.uni-mainz.de) for writing YABASIC which has become
          predecessor of SampLin's script language
        * People around the KDE project for creating 1st consistent and
          free desktop for linux
        * Claus Schroeter (www.llp.fu-berlin.de) for writing the Linux
          GPIB package
        * Josef Wilgen (jwlg@mail.desy.de) for writing Qwt - The Qt
          Widget Library for Technical Applications
        * Jochen Wilhelmy for writing the kwrite editor

     ... and everybody else who helped me with SampLin development.
