----- file created by makedoc on: Thu Nov  5 15:14:57 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/readsh.pro -----

 NAME:
	READSH
 PURPOSE:
	to load in an IDL structure a SHADOW  file. It can also be
	used to write a new idl/shadow structure with fewer rays by
	using the NOLOST keyword, or to append data into a shadow/
	idl structure by using the APPEND keyword.
 CATEGORY:
	SHADOW's utilities.
 CALLING SEQUENCE:

	Result = readsh('shadow_file_name')

	with that, IDL stores in a structure named Result (or whatever you
	want) the shadow_file_name (for instance, begin.dat).

   For help, type

	HELP,/ST,Result
 INPUTS:
	SHADOW_FILE_NAME name of the input file (or a idl/shadow
	  structure; see NOLOST keyword)
 KEYWORD PARAMETERS:
	NFILES = number of files to be read. Optionally READSH can read
	a number of files from an iterative shadow run. These files must
	have the extension -1,-2...-n (i.e.  star.01-1,star.01-2,star.01-3)
	where - acts as a "seperator". The separator can be any sign 
	defined in the SEPARATOR keyword
	SEPARATOR = sign that acts a separator between the file name and
	the run number (default='-')
       NOLOST = consider losses in the returned shadow/idl structure
            0 all rays (default option)
            1 exclude losses;
            2 only losses;
       APPEND Set this keyword to a shadow file or idl shadow structure
	     to be appended. Thus Result=InFile+AppendedFile.
	GROUP The parent id for the caller widget (used to positioning
		error and information windows).
       VERBOSE Set this keyword to print some info (Default: verbose=1)
	
 OUTPUTS:
	A1 an IDL structure 
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None
 RESTRICTIONS:
	None.
 PROCEDURE:
 	
 EXAMPLES:
	1) read a shadow file and write it into a shadow/idl structure:
		a=readsh('begin.dat')
	2) same but using only good rays:
		a=readsh('star.01',/nolost)
	3) save 8 files (star.01-1, ..., star.01-8) in a shadow/idl str:
		a=readsh('star.01',nfiles=8)
	4) remove the bad rays from a shadow/idl structure
		a=readsh(a,/nolost)
	5) read the file 'star.05' five times and place the result in a:
		a=1 ; initialize variable
		for i=1,5 do a=readsh('star.05', append=a)
 MODIFICATION HISTORY:
	M. Sanchez del Rio. ESRF. Grenoble, May 1991
        92-07-09 MSR includes a 'spawn' call in order to run sh-idl from idl
        92-10-17 MSR includes NFILES option
        93-07-09 MSR includes SEPARATOR keyword
        94-06-09 MSR if the input is not a file, but a SHADOW-IDL
		structure, then returns this (the same) structure. This check 
		is done here, and can therefore be removed from the other 
		routines.
        94-11-29 MSR adds the /NOLINK flag, which is passed to getrays
        95-03-03 MSR removes the /NOLINK flag, unnecessary with the 
		new getrays function
	 96-06-18 MSR adds NOLOST keyword, updates doc, small changes.
	 98-04-02 MSR adds GROUP keyword.
	 2009-01-12 MSR adds VERBOSE keyword.

