% @(#)write_desc.hlq	17.1.1.2 (ESO-IPG) 02/25/02 17:46:25 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      write_desc.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, WRITE/DESCRIPTOR
%.PURPOSE    On-line help file for the command: WRITE/DESCRIPTOR
%.VERSION    1.0  17-OCT-1983 : Creation, KB
%.VERSION    1.1  16-MAR-1993 : Update, KB
%----------------------------------------------------------------
\se
SECTION./DESC
\es\co
WRITE/DESCR					08-JAN-2002  KB
\oc\su
WRITE/DESCR frame descr data [flg]
	store values into a descriptor
\us\pu
Purpose: 
           Store values into a descriptor.
\up\sy
Syntax:  
           WRITE/DESCR frame descr data [flg]
\ys\pa
           frame = name of data file
\ap\pa
           descr = complete descriptor specification, name/type/felem/nval,
               e.g. NPIX/I/1/2
               or only descriptor name, e.g. NPIX, if the descriptor exists
               already.
               `nval' data values will be written into the descriptor `name'
               of given type, beginning at element `felem'.
\ap\pa
           data = data values, separated by a comma
\ap\pa
           flg = optional flag, if set to ALL, the descriptor will be filled
               completely with the value given as data, so you set all
               descriptor elements to that value
\ap\sa
See also:
           READ/DESCR, SHOW/DESCR, PRINT/DESCR, DELETE/DESCR, COPY/DD
           WRITE/DHELP, COPY/AD, @a dscedit
           chapter 3 of MIDAS Users guide, volume A
\as\no
Note:  
           In order to support ESO's hierarchical FITS keywords the length
           of descriptor names has been extended to a maximum length of 48 
           characters (previously 15 chars).
           Valid descriptor types are I for integer, L for logical,
	   R for real, D for double precision, C for character descriptors 
	   and C*nnn for character array descriptors.
           Integer descriptors can also be filled with hex. data by preceding
           the data values with `0x'.
	   The elements of logical descriptors are implemented as integer
	   data. Like in C, a value of 0 means False, anything else is True.
	   All nonzero data are stored as 1 in the logical descriptor.
           Descriptors are extended automatically (like a file is extended if
           needed when it is edited) by writing more elements or by starting at
           an element larger than the no. of elements defined in the
           descriptor creation.
	   If the no. of elements to write for a char. descr. is more
	   than the size of the data string, it's padded with blanks.
           To write the contents of an ASCII file into a descriptor use the
           command COPY/AD.
           Beware, you can create holes like that...
           To edit an existing descriptor use the application procedure
           `dscedit.prg', enter "HELP/APPLIC dscedit" to get details.
\on\exs
Examples:
\ex
           WRITE/DESCR dinosaur RR/R/1/5 1.,2.,3.,4.,5.
             Set real descriptor elements RR(1), ..., RR(5) of frame
             `dinosaur.bdf' to 1.,2.,3.,4.,5. If the descriptor RR had been
             created before with 3 elements only, it would be extended
             automatically.
\xe\ex
           WRITE/DESCR fossil ck/c/1/20 "abcdefghij 123456789"
             Define character descriptor `ck' as a "flat" string, like
             "CHARACTER CK*20" in FORTRAN or "char ck[20]" in C,
             and fill it with the 20 char. string 'abcdefghij 123456789'.
             Note, that the string must be enclosed in double quotes ("),
             because it contains a blank (which is the delimiter in MIDAS).
\xe\ex
           WRITE/DESCR fossil cmore/c*5/1/10 abcde all
             Define character descriptor `cmore' as a character array,  like
             "CHARACTER CMORE(10)*5" in FORTRAN or "char cmore[10][5]" in C,
             and fill all its 10 elements (which are strings of 5 chars.) with
             the string 'abcde'.
\xe\ex
           WRITE/DESCR hippo flag_set/L/1/1 1
             Set first element of logical descriptor flag_set of frame
	     hippo.bdf to TRUE.
\xe\ex
           WRITE/DESCR trex idsc/i/1/3 0xff,10,-0xaaa
             Set the elements of integer descriptor idsc of frame `trex.bdf'
             to 255, 10 and -2730.
\xe\ex
           WRITE/DESCR trex coco/c/1/20 abc
             Set the first 20 elements of char. descriptor coco of frame 
	     `trex.bdf' to "abc                 ".
\xe\ex
           WRITE/DESCR hippo.tbl ir/i/1/5 55 all
             Set the first 5 elements of integer descriptor IR of table file
             `hippo.tbl' to 55.
\xe\ex
           WRITE/DESCR rhino save_the_last_free_roaming_rhinos/d/1/2 1.,2.
             Create a double precision descriptor of 2 elements, named
             "save_the_last_free_roaming_rhinos" for image `rhino.bdf'.
\xe \sxe