%****************************************************************************/
%
% File:		sample.tex
%
% Project:	xdevmenu application documentation
%
% Description:	"A sample execution" section
%
% Author(s):	Faranguiss Poncet
%
% Original:	March 1991
%
%
% $Header: /cvsroot/taco/taco/system/xdevmenu/doc/sample.tex,v 1.2 2003/12/17 14:24:25 jkrueger1 Exp $
%
% Copyright (c) 1990 by European Synchrotron Radiation Facility, 
%                       Grenoble, France
%
%		       All Rights Reserved
%
%****************************************************************************/
The sample execution described in this section illustrates how a user can
start the application, execute a command on a device, change the device
location option, close a device and finally quit the application.

The screen hardcopies added in Appendix A help you to follow the steps of
the execution.

If xdevmenu is run on any of the HP 300's ( ie whisky, gin ) in the control 
room, a man page for the use of xdevmenu is available on whisky, gin and leo. 
Otherwise, 
before starting the application, and to make xdevmenu run on the HP 300's in the computer room, some environment variables have to be set first.
 A man page is also available on mars. 
NETHOST and XAPPLRESDIR have to be set as the following :
\begin{itemize}
\item
{ NETHOST : }the shell command (using Bourne shell or Korn shell) to be typed
is "NETHOST=mars; export NETHOST".
\item
{ XAPPLRESDIR : }the shell command (using Bourne shell or Korn shell) to be typed
is "XAPPLRESDIR=/usr/local/app-defaults; export XAPPLRESDIR".
\end{itemize}

The following path  /usr/local/bin  must be added to the
PATH environment variable.

The LANG environment variable has to be unset.

Don't forget to use the xhost command and set the DISPLAY environment variable 
correctly in order to allow the machine where xdevmenu is executed from, to display on the requested terminal.

To start the application, the user only needs to type the name of the executable
file which is "xdevmenu". There isn't any specific argument to define at
this stage.

\subsubsection{Opening the device "TL1/PS-D/D"}

The user first needs to choose the "File" command and then in the associated
pulldown menu, he should choose "Open Device". 
A window displaying a list of device names will appear. If that list is empty,  
the user should check if the environment variable XAPPLRESDIR is set correctly.
 Whether this list is empty or not, the user can either type the name of the  
device to be opened or select it in the list.

Click on the item "TL1/PS-D/D" and select the "Open Device"
pushbutton.

If the connection is established successfully, an icon will appear in the
application main window. On the bottom of the icon the name of the device is
displayed~: "TL1/PS-D/D". Both the icon and a window displaying 
after a command has been executed, the output 
arguments and the error messages received from this device, will appear. This 
window is named " out and error window " in the rest of the document.

\subsubsection{Executing "DevState" "DevStatus" "DevSetValue" and 
"DevReadValue"}

Choose in the "Edit" pulldown menu the "ShowState" entry and you will see 
appearing in an error dialog window the following error message~:
" Please SELECT a device by clicking on a device name. "

Click on the icon label representing "TL1/PS-D/D" to select the device 
and have the list of all available
command names for "TL1/PS-D/D" displayed in a selection dialogue window.

If you choose again in the "Edit" pulldown menu the "ShowState" entry or if 
you choose to execute the "DevStatus" command by clicking on the icon pixmap
of the "TL1/PS-D/D" device, the output arguments resulting from this(these) 
execution(s) will appear in the bottom part of the out and error window.

The "DevSetValue" command is part of the list of the available commands for
the "TL1/PS-D/D" device. Click then on the "DevSetValue" item and select
the "Execute" pushbutton in the window. Since this command does require 
an input argument, a dialogue window will appear displaying the input argument 
you should provide. Enter a float value and click on the "Ok" pushbutton. 
If for some reasons the command can not be executed, an error message received 
from the device server will appear in the bottom part of the out and error 
window. If the command is executed successfully, the date, time and name of the
command will appear in the top part of the out and error window. 
You can therefore check the output arguments resulting from this execution by 
reading the device value. Select the "DevReadValue" item in the command list 
and click on the "Execute" pushbutton. The output argument will appear in the 
top part of the out and error window.

After that, click on the "DevOff" item ( beware if you are accessing a  
real device ! ), and select the "Execute"  
pushbutton in the window. Repeat then the same operation for the 
"DevReadValue" command.
An error message received from the device server will appear in the bottom part of the out and error window.

\subsubsection{Changing the device location}

Select the "Device location" in the "Option" pulldown menu. A dialogue
window will appear with two text inputs, one in which you can type the new device location, and the other in which a subdirectory filter can be specified.
Choose the "Change location" pushbutton to confirm.

To open a device in this new device location, you should select the open
device function from the "File" pulldown menu, and simply select in the new
device list displayed the device you want to open.

\subsubsection{Closing "TL1/PS-D/D"}

To close this device, select first the associated icon by clicking on its icon label and then select the "Close Device" command in the "File" pulldown menu. 

A question dialogue window will appear asking you to confirm your demand.
Click on the "Ok" button if you really want to close the connection to
that device.

\subsubsection{Ending the execution}

To end the execution of the application, simply select the "Quit" command
from the "File" pulldown menu.

