PARSE_DATACOLLECTION(3)


     NAME
	  parse_list, parse_list_force,	parse_dataname,
	  parse_datacollection,	parse_datasuperset, parse_class,
	  parse_data_selector, parse_range, expand_range, add_member,
	  replicate_name, add_paths, add_directory, add_basename,
	  add_env_template, fitsname, fitsname_noseries, logname,
	  tlmname, datasetname

	  - functions to parse data names

     SYNOPSIS
	  #include <soi_names.h> #include <soi_key.h>

	  int parse_list (KEY  **params, char *	root); int
	  parse_list_force (KEY	 **params, char	* root); KEY
	  *parse_dataname (char	*name, char *root); KEY
	  *parse_datacollection	(char *collection, char	*root);	KEY
	  *parse_datasuperset (char *superset, char *root); KEY
	  *parse_class (char *class, char *root); KEY
	  *parse_data_selector (char *selector,	char *root); KEY
	  *parse_range (char *range, char *root); char *expand_range
	  (char	*member_range);	void add_member	(KEY *member); void
	  replicate_name (char *name, KEY** inlist, char *root); int
	  add_paths (KEY **tolist, char	*root);	int add_directory (KEY
	  **tolist, char *root); int add_basename (KEY **tolist, char
	  *root); int add_env_template (KEY **tolist, char *root);
	  char *fitsname (KEY *params, char *root, int sn); char
	  *fitsname_noseries (KEY *params, char	*root, int sn);	char
	  *logname (KEY	*params, char *root); char *tlmname (KEY
	  *params, char	*root);	char *datasetname (KEY *params,	char
	  *root);



     DESCRIPTION
	  This set of functions	parses data names according to Phil
	  Scherrer's 93.03.31 memo " Use of DataSet Names" and
	  revisions to handle data collections and array slices.  The
	  FORMAL SYNTAX	and descriptions of the	changes	can be found
	  in the ReadMe	file in	the source directory for names.c.

	  Those	functions which	return pointers	return NULL when
	  errors occur.	 The value of soi_errno	should indicate	the
	  kind of error.

	  parse_list takes a pointer to	a keylist and a	rootkey
	  (character string) as	arguments.  It assumes that there is
	  an entry in the given	keylist	whose key is the rootkey and
	  whose	value is a datacollection_name to be parsed.  It
	  parses this datacollection_name and expands the given	list
	  to include entries for the parsed components of the
	  datacollection_name.	Entries	for directories	and basenames
	  formed from those components are also	added to the list if a
	  template can be found	in the list or in the environment. The
	  ke ys	for the	entries	are of the form	root_partname and
	  root_n_partname.  The	index n, starting with 0, indicates
	  the ordering of the components within	the datacollection.
	  parse_list is	the only parsing function which	should need to
	  be called by a top-level interface in	order to pass a
	  keylist to a strategy	module.	 parse_list calls the other
	  parsing functions described here.  It	returns	0 if the
	  parsing is successful.

	  parse_list_force is the same as parse_list.  It exists for
	  backwards compatibility.

	  parse_dataname takes two character strings, a
	  datasubset_name and a	rootkey, as arguments. It separates
	  the data and selector	portions of the	datasubset_name	and in
	  turn parses whichever	of these (or both) is found.  It
	  returns a pointer to a keylist which contains	entries	for
	  the parsed components.

	  parse_datacollection takes two character strings, a
	  datacollection_name and a rootkey, as	arguments.  It parses
	  the datacollection_name and returns a	pointer	to a keylist
	  which	contains entries for a ordered set of components of
	  the datacollection_name.

	  parse_datasuperset takes two character strings, a
	  data*set_name	and a rootkey, as arguments and	returns	a
	  pointer to a keylist which contains entries for the parsed
	  components.

	  parse_class takes two	character strings, a
	  [project|class|series|member]_[selector|collector] and a
	  rootkey, as arguments	and returns a pointer to a keylist
	  which	contains entries for the parsed	components.

	  parse_data_selector takes two	character strings, a
	  data_selector	and a rootkey, as arguments and	returns	a
	  pointer to a keylist which contains entries for the parsed
	  components.

	  parse_range takes two	character strings, a record_range and
	  a rootkey, as	arguments and returns a	pointer	to a keylist
	  which	contains entries for the parsed	components. These
	  entries can include first number, last number, and
	  increment.

	  expand_range takes a character string, a member_range, as an
	  argument and returns a character string which	contains a
	  comma	separated list of numbers.  The	returned pointer is a
	  pointer to a static character	array whose contents is
	  destroyed by the next	call to	this function.	There is no
	  check	for maximum string length.

	  add_member takes a pointer to	a keylist member as an
	  argument and adds this member	to a global keylist called
	  __collection_list.  This function add_member is used by
	  parse_datacollection as an argument to the keylist function
	  keyiterate.  It should not be	used in	any other context.

	  replicate_name takes a character string (name), a pointer to
	  a keylist (inlist), and a rootkey as arguments. If an
	  integer value	for root_nsets exists in inlist	and either a
	  string or integer value for root_name	exist in inlist	the
	  value	is replicated in the list nsets	times with keys
	  root_0_name, ...  It is used by parse_list to	insert a dbase
	  entry	for each element of a datacollection.

	  add_paths takes a pointer to a keylist and a rootkey as
	  arguments and	adds directory and basename entries to list
	  for multiple datasets.  It uses the functions	add_directory
	  and add_basename.

	  add_directory	takes a	pointer	to a keylist and a rootkey as
	  arguments. If	there is a template in the given list or if a
	  template can be obtained from	the environment, it is applied
	  to the list entries to form a	directory name which is	then
	  added	to the list. If	there is no template the directory
	  name is an empty string. If an error occurs, the list	is
	  unchanged and	status is returned. It will NOT	OVERRIDE and
	  existing root_wd entry in the	list.


	  add_basename takes a pointer to a keylist and	a rootkey as
	  arguments. If	there is a template in the given list or if a
	  template can be obtained from	the environment, it is applied
	  to the list entries to form a	basename which is then added
	  to the list. If there	is no template the basename is an
	  empty	string.	If an error occurs, the	list is	unchanged and
	  status is returned.

	  add_env_template takes a pointer to a	keylist	and a rootkey
	  as arguments.	It tries to add	the template from the
	  environment corresponding to the proj	or prog	name IF	there
	  is not a template already in the list. i.e. it does not
	  override an existing template. Failure to find a template in
	  the environment is not considered an error.

	  fitsname forms a .fits file name from	keylist	parameters for
	  the given rootkey and	sn and returns a pointer to the
	  malloced name.

	  fitsname_noseries is the same	as fitsname except that	it
	  does not use a basename when forming a filename.  This
	  function should be phased out.  The same effect can be
	  achieved by calling fitsname with a list which includes an
	  empty	string entry for the basename.

	  logname forms	a .log filename	from keylist parameters	for
	  the given rootkey and	returns	a pointer to the malloced
	  name.

	  tlmname forms	a .tlm filename	from keylist parameters	for
	  the given rootkey and	return s a pointer to the malloced
	  name.

	  datasetname forms a name string from keylist parameters for
	  the given root and returns a pointer to the malloced name;
	  the returned name is just the	normal full data name
	  (prog:...) without the possible fmt: field at	the end.  Note
	  that with the	data collection	revisions to the names
	  parsing, datasetname only returns a data set name in a
	  special.  It exists for backwards compatibility.



     OPTIONS
	  none

     EXAMPLES
	  see soi strategy modules

     SEE ALSO
	  keylists(3) Use of DataSet Names, PHS	31 March 93 SOI-MDI
	  Technical Note 104 - Naming of Datasets for SOI


     DIAGNOSTICS
	  none

     BUGS
	  none known

     HISTORY
	  1993-09-17
	  1994-02-08 SOI Version 0.8