STRUCTURE

• ALIGN_STRUCT
• COMPARE_STRUCT
• COPY_STRUCT
• COPY_STRUCT_INX
• CREATE_STRUCT
• N_STRUCT
• PRINT_STRUCT
• SIZE_STRUCT
• WHERE_TAG

Routine Descriptions

 NAME:
	ALIGN_STRUCT
 PURPOSE:
	Check an IDL structure for standard memory alignment of fields,
	insert any byte padding required to align fields on size boundaries,
	write out new code to define the aligned version of structure.
 CATEGORY:
			Structures
 CALLING SEQUENCE:
			align_struct, structure_name
	examples:
			align_struct, "fdq_sdf"
 INPUTS:
		structure_name = string giving the structure name
				as known by IDL (help,/struct,variable).

 inputs/outputs used recursively:
		struct = the structure variable currently analyzed.
		Max_Field_Size = size of the largest field found in structure.
		struct_size = total size of all fields in structure.
		Lun_out = Logical unit number for writing .PRO code.

 SIDE EFFECTS:
		"structure_name"_ST_AL.PRO is created (IDL function code).
 PROCEDURE:
		Strategy is to call align_struct recursively.

  otherwise the field type and size is used to construct IDL definition,
	which is then concatenated with the other IDL definitions,

 MODIFICATION HISTORY:
	written 1990 Frank Varosi STX @ NASA/GSFC

(See /usr/local/idl/lib/zastron/structure/align_struct.pro)

 NAME:
	compare_struct
 PURPOSE:
 	Compare all matching Tags names (except for "except_Tags")
	between two structure arrays (may be different struct.defs.),
	and return a structured List of fields found different.
 CATEGORY:
			Structures
 CALLING SEQUENCE:
		compare_struct, struct_A, struct_B
		compare_struct, struct_A, struct_B, EXCEPT=["imscaled","info"]
		compare_struct, struct_A, struct_B, /RECUR_A
 INPUTS:
	struct_A, struct_B : the two structure arrays to compare.
	Struct_Name : only used internally during recursion.
 KeyWords:
		EXCEPT = string array of Tag names to ignore (NOT to compare).
		/BRIEF = number of differences found for each matching field
						of two structures is printed.
		/FULL = option to print even if zero differences found.
		/RECUR_A = option to search for Tag names
				in sub-structures of struct_A,
				and then call compare_struct recursively
				for those nested sub-structures.
		/RECUR_B = search for sub-structures of struct_B,
				and then call compare_struct recursively
				for those nested sub-structures.
	Note:
		compare_struct is automatically called recursively
		for those nested sub-structures in both	struct_A and struct_B
		(otherwise cannot take difference)
 RESULT of FUNC:
		Structure array describing differences found.
 PROCEDURE:
		Match Tag names and then use corresponding Tag numbers.
 MODIFICATION HISTORY:
	written 1990 Frank Varosi STX @ NASA/GSFC (using copy_struct)
	modif Aug.90 by F.V. to check and compare same # of elements only.

(See /usr/local/idl/lib/zastron/structure/compare_struct.pro)

 NAME:
	copy_struct
 PURPOSE:
 	Copy all Fields with matching Tags names (except for "except_Tags")
	from one structure array to another structure array (may be different).
	Can also recursively copy from/to structures nested within structures.
 CATEGORY:
			Structures
 CALLING EXAMPLES:
		copy_struct, struct_From, struct_To
		copy_struct, struct_From, struct_To, EXCEPT=["imagscal","tag"]
		copy_struct, struct_From, struct_To, /RECUR_FROM
 INPUTS:
		struct_From = structure array to copy from.
		struct_To = structure array to copy values to.
 KEYWORDS:
		EXCEPT_TAGS = string array of Tag names to ignore (NOT to copy).

		SELECT_TAGS = Tag names to copy (takes priority over EXCEPT).

		/RECUR_FROM = option to search for Tag names
				in sub-structures of struct_From,
				and then call copy_struct recursively
				for those nested structures.
		/RECUR_TO = search for sub-structures of struct_To,
				and then call copy_struct recursively
				for those nested structures.
		/RECUR_TANDEM = call copy_struct recursively
				for the sub-structures with matching
				Tag names in struct_From and struct_To
		(for use when Tag names match but structure types differ).
 OUTPUTS:
		NF_copied = incremented by total # of Fields copied (optional)
 INTERNAL:
	Recur_Level = # of times copy_struct calls itself.
		This argument is for internal recursive execution only.
		The user call is 1, subsequent recursive calls increment it,
		and the counter is decremented before returning.
		The counter is used just to find out if argument checking
		should be performed, and to set NF_copied = 0 first call.
 SIDE EFFECTS:
		The arrays of values for tags in struct_From
		are copied to tags with matching names in struct_To.
 CALLS:
		For option SELECT_TAGS calls pro match.
 METHOD:
		Match Tag names and then use corresponding Tag numbers.
 MODIFICATION HISTORY:
	written 1989 Frank Varosi STX @ NASA/GSFC
 	modif Jul.90 by F.V. added option to copy sub-structures RECURSIVELY.
	modif Aug.90 by F.V. adjust # elements in TO (output) to equal
			# elements in FROM (input) & count # of fields copied.
	modif Jan.91 by F.V. added Recur_Level as internal argument so that
			argument checking done just once, to avoid confusion.
			Checked against Except_Tags in RECUR_FROM option.
	modif Oct.91 by F.V. added option SELECT_TAGS= selected field names.

(See /usr/local/idl/lib/zastron/structure/copy_struct.pro)

 NAME:
	copy_struct_inx
 PURPOSE:
 	Copy all Fields with matching Tags names (except for "except_Tags")
	from one structure array to another structure array (may be different).
	Can also recursively copy from/to structures nested within structures.
	This procedure is same as copy_struct with addition of option to
	specify indices (subscripts) of which elements to copy.
 CALLING EXAMPLES:
		copy_struct_inx, struct_From, struct_To, INDEX_FROM= where(...)
 INPUTS:
		struct_From = structure array to copy from.
		struct_To = structure array to copy values to.
 KEYWORDS:
		EXCEPT_TAGS = string array of Tag names to ignore (NOT to copy).

		SELECT_TAGS = Tag names to copy (takes priority over EXCEPT).

		/INDEX_FROM = indices (subscripts) of which elements to copy.
		/INDEX_TO = indices (subscripts) of which elements to copy To.
						(defaults are all elements)

		/RECUR_FROM = option to search for Tag names
				in sub-structures of struct_From,
				and then call copy_struct_inx recursively
				for those nested structures.
		/RECUR_TO = search for sub-structures of struct_To,
				and then call copy_struct_inx recursively
				for those nested structures.
		/RECUR_TANDEM = call copy_struct recursively
				for the sub-structures with matching
				Tag names in struct_From and struct_To
		(for use when Tag names match but structure types differ).
 OUTPUTS:
		NF_copied = incremented by total # of Fields copied (optional)
 INTERNAL:
	Recur_Level = # of times copy_struct_inx calls itself.
		This argument is for internal recursive execution only.
		The user call is 1, subsequent recursive calls increment it,
		and the counter is decremented before returning.
		The counter is used just to find out if argument checking
		should be performed, and to set NF_copied = 0 first call.
 SIDE EFFECTS:
		The indexed portion arrays of values for tags in struct_From
		are copied to tags with matching names in struct_To.
 CALLS:
		For option SELECT_TAGS calls pro match.
 METHOD:
		Match Tag names and then use corresponding Tag numbers,
		apply the sub-indices during = and recursion.
 MODIFICATION HISTORY:
	adapted from copy_struct: 1991 Frank Varosi STX @ NASA/GSFC

(See /usr/local/idl/lib/zastron/structure/copy_struct_inx.pro)

 NAME:
	CREATE_STRUCT
 PURPOSE:
	Dynamically create an IDL structure variable from list of tag names 
	and data types of arbitrary dimensions.   Useful when the type of
	structure needed is not known until run time.

 CALLING SEQUENCE:
	CREATE_STRUCT, STRUCT, strname, tagnames, tag_descript, [ DIMEN = ,
		CHATTER=  , NODELETE = ]

 INPUTS:
	STRNAME -   name to be associated with structure (string)
		   Must be unique for each structure created.   Set
		   STRNAME = '' to create an anonymous structure

	TAGNAMES -  tag names for structure elements
		    (string or string array)

	TAG_DESCRIPT -	String descriptor for the structure, containing the
		tag type and dimensions.  For example, 'A(2),F(3),I', would
		be the descriptor for a structure with 3 tags, strarr(2), 
		fltarr(3) and Integer scalar, respectively.
		Allowed types are 'A' for strings, 'B' or 'L' for unsigned byte 
		integers, 'I' for integers, 'J' for longword integers, 
		'F' or 'E' for floating point, 'D' for double precision
		Uninterpretable characters in a format field are ignored.

		For vectors, the tag description can also be specified by
		a repeat count.  For example, '16E,2J' would specify a 
		structure with two tags, fltarr(16), and lonarr(2)

 OPTIONAL KEYWORD INPUTS:
	DIMEN -	   number of dimensions of structure array (default is 1)

       CHATTER -  If /CHATTER is set, then CREATE_STRUCT will display
                  the dimensions of the structure to be created, and prompt
                  the user whether to continue.  Default is no prompt.

       NODELETE - If /NODELETE is set, then the temporary file created
                  CREATE_STRUCT will not be deleted upon exiting.   See below

 OUTPUTS:
	STRUCT -   IDL structure, created according to specifications 

 EXAMPLES: 

       IDL> create_struct, new, 'name',['tag1','tag2','tag3'], 'D(2),F,A(1)'

       will create a structure variable new, with structure name NAME

       To see the structure of new:

       IDL> help,new,/struc
       ** Structure NAME, 3 tags, 20 length:
          TAG1            DOUBLE         Array(2)
          TAG2            FLOAT          0.0
          TAG3            STRING         Array(1)

 PROCEDURE:
	Generates a temporary procedure file using input information with
       the desired structure data types and dimensions hard-coded.
       This file is then executed with CALL_PROCEDURE.

 NOTES:
	A temporary .pro file is created to define structure in the default
	directory, so writing privileges are required.   

	At present, can fail if a tag_name cannot be used as a proper
	structure component definition, e.g., '0.10' will not
	work, but a typical string like 'RA' or 'DEC' will.
	A partial workaround checks for characters '\' and '/'
	and '.' and converts them to '_'. in a tag_name.

       Note that 'L' now specifies a LOGICAL (byte) data type and not a
       a LONG data type for consistency with FITS binary tables

 RESTRICTIONS:
	The name of the structure must be unique, for each structure created.
	Otherwise, the new variable will have the same structure as the 
	previous definition (because the temporary procedure will not be
	recompiled).  ** No error message will be generated  ***

 SUBROUTINES CALLED:
	function gettok, function repchr 

 MODIFICATION HISTORY:
	Version 1.0 RAS January 1992
       Modified 26 Feb 1992 for Rosat IDL Library (GAR)
	Modified Jun 1992 to accept arrays for tag elements -- KLV, Hughes STX
	Accept anonymous structures W. Landsman  HSTX    Sep. 92
	Accept 'E' and 'J' format specifications   W. Landsman Jan 93
	'L' format now stands for logical and not long array
	Accept repeat format for vectors        W. Landsman Feb 93

(See /usr/local/idl/lib/zastron/structure/create_struct.pro)

 NAME:
	N_struct

 PURPOSE:
	To determine if variable is a structure and return number of elements.

 CALLING:
	n = N_struct( var, ntags )

 INPUT:
	var = any variable.

 OUTPUT:
	ntags = number of structure tags.

 RESULT:
	Returns zero if variable is not a structure, otherwise returns # elems.

 PROCEDURE:
	Determine if argument is a structure by checking for # of tags.
	If structure, use size function to get # of elements
	(instead of N_elements) so that it works on I/O associated structures.

 MODIFICATION HISTORY:
	Written, Frank Varosi NASA/GSFC 1989.

(See /usr/local/idl/lib/zastron/structure/n_struct.pro)

 NAME:
	print_struct

 PURPOSE:
	Print the fields of an array of structures in nice column format,
	with header line of field names.

 CALLING SEQUENCE:

	print_struct, structure, tags_print, LUN_OUT=Lun

 INPUTS:
	structure = array of structured variables

	tags_print = string array specifying the names of fields to print.
			Default is to print all fields which are not arrays.
 KEYWORDS:
	LUN_OUT = Logical unit number for output to a file,
		default is to print to standard output.

 EXTERNAL CALLS:
	function N_struct
 PROCEDURE:
	Check the types and lengths of fields to decide formats,
	then loop and print requested fields.
 HISTORY:
	Written, Frank Varosi NASA/GSFC 1991.
	F.V.1993, fixed up the print formats.

(See /usr/local/idl/lib/zastron/structure/print_struct.pro)

 NAME:
	SIZE_STRUCT
 PURPOSE:
	Obtain the size in bytes of an IDL structure definition.
 CATEGORY:
			Structures
 CALLING SEQUENCE:
			bytes = size_struct( structure )
	examples:
			print, size_struct( "fdq_sdf" )
 INPUTS:
		structure = a structure variable or
				a string giving the structure name
				as known by IDL (help,/struct,variable).
		/PRINT = to print all sub structure sizes.

 inputs/outputs used recursively:
		struct = the structure VARIABLE currently analyzed.
		Max_Field_Size = size of the largest field found in structure.
 RESULT:
		Function returns the total size in bytes of a structure element.
 PROCEDURE:
		Strategy is to call size_struct recursively if
		structure contains sub-structures.
		Otherwise just add up the field sizes.

 MODIFICATION HISTORY:
	written 1990 Frank Varosi STX @ NASA/GSFC (using align_struct).

(See /usr/local/idl/lib/zastron/structure/size_struct.pro)

 NAME:
	WHERE_TAG
 PURPOSE:
	Obtain subscripts of elements in structure array for which
	a particular Tag has values in a range or matching specified values.
	Like the WHERE function but for use with structures
 CATEGORY:
			Structures
 CALLING SEQUENCE:
	 w = where_tag( struct, [ Nfound,  TAG_NAME=, TAG_NUMBER = , RANGE =, 
				VALUES =, RANGE =, ISELECT =, /NOPRINT ]

 INPUTS:
	Struct = structure array to search.

 INPUT KEYWORDS:
	User *must* specify (1) TAG_NAME or TAG_NUMBER to search, and (2)
		the VALUES or RANGE to search on

	TAG_NAME = Scalar string specifying Tag Name
	TAG_NUMBER = otherwise give the Tag Number,
	RANGE = [min,max] range to search for in Struct,
	VALUES = one or array of numbers to match for in Struct,
	ISELECT= specifies indices to select only part of structure array,
		(use it to recycle subscripts from previous searches).
	/NOPRINT = suppress informational messages about nothing found.

 OUTPUTS:
	Nfound = # of occurences found.

 RESULT:
	Function returns subscripts (indices) to desired elements.

 EXAMPLES:
	Suppose STR is a structure with tags CAT_NO:indgen(10), and 
		NAME:strarr(10).   Find the indices where STR.CAT_NO is
		between 3 and 5.

	IDL> print, WHERE_TAG( str, TAG_NAME = 'CAT_NO', VALUE = [3,4,5] )  ;or
	IDL> print, WHERE_TAG( str, TAG_NUM = 0, RANGE = [3,5]) 

 PROCEDURE:
	Get tag number and apply the WHERE function appropriately.

 MODIFICATION HISTORY:
	written 1990 Frank Varosi STX @ NASA/GSFC

(See /usr/local/idl/lib/zastron/structure/where_tag.pro)