REPLICATE_NAME(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