set_info - Add or update records with new keyword or segment filename values
[DRMS Utilities]

Collaboration diagram for set_info - Add or update records with new keyword or segment filename values:

Synopsis:

set_info [-h] 
set_info [-ciktv] [JSOC_FLAGS] ds=<seriesname> [<keyword>=<value>]... [<segment>=<filename>]... [<link>=<record-set specification>]...
set_info [-Cimtv] [JSOC_FLAGS] ds=<record_set> [<keyword>=<value>]... [<segment>=<filename>]... [<link>=<record-set specification>]...
set_info_soc {options as above}

Sets keyword values for a record in a DRMS dataseries. set_info runs in one of two modes.

If a "create" -c or -k flag is present a new record will be created. In this case ALL of the prime keys must be present in keyword=value pairs to specify the locator keywords for the new record. Other keywords and or segments specifications are usually also present. If -c is set then a single record will be created and populated from the command line. If the -k flag is set stdin will be read for a set of records in the same format as produced by show_info -k and a record will be created for each record specified in the stdin file.
An existing record_set may be specified and a new version of those record will be made with the specified keywords given new values. Usually, almost always, only a single record is updated in one call of set_info since only one set of keyword values can be provided and all records modified will be given the same new values for those keywords. If multiple records are to be changed the -m flag is required. set_info will then clone the records specified by the record-set filter. In the update mode, NONE of the prime keys are allowed in keyword=value pairs on the command line (except of course as a where clause as part of the recordset specification)

For each keyword specified in a keyword=value pair on the command line, set_info will set the values for all these clones' keywords to value.

If a segment in the series is of type generic then set_info can be used to store a given file in the SUMS directory associated with the record. In this case, for each segment=filename parameter the file found at filename will be copied into the record directory and the segment filename will be saved in the segment descriptor in DRMS.

If a segment= <filename> argument specifies the path to a FITS file, then set_info will parse the FITS-file header. For each header keyword, set_info examines the set of series' DRMS keywords. If the header-keyword name matches the name of such a DRMS keyword, then set_info assigns the header-keyword's value to the DRMS keyword. If there exists such a DRMS header keyword, and the DRMS keyword also appears as the name of an argument on the command line, then the command-line argument value takes precendence over the value in the FITS-file header. The header-keyword value is ignored in this case. This default behavior can be disabled with the -i flag. If the -i flag is present on the command line, along with the segment= <filename> argument where <filename> is a FITS file, then the entire FITS-file header is not parsed and is essentially ignored by set_info.

In no case is a constant DRMS-keyword value updated by set_info. If a constant DRMS keyword is specified on the command line, then set_info exits with an error. If a FITS file is specified on the command line, the module simply ignores FITS-file header keywords that correspond to constant DRMS keywords.

In normal usage if NO segments are specified, any segments in the original version of an updated record will be shared with the new record. This allows keyword metadata to be updated without making unnecessary copies of file data in SUMS. However if any segment file is to be updated, a new record directory must be allocated and any other segment's files will be copied (cloned) to the new directory and associated with the new record. If the -C "clone" flag is present then a new record directory will be allocated even if none of the segments are to be updated. This usually only makes sense in a JSOC session script where the same record will be incrementally updated by multiple modules and set_info is invoked as set_info_sock. For each link argument specified, the argument name must match the name of a link in the series. The argument value for each such argument must be a record-set specification that identifies a single record in a target series. If these conditions are met, then for each link argument specified, a link between the newly created record and the record specified by the record-set specification will be created.

Only one instance of each keyword name or segment name is allowed.

Options:

Flags:

-c: Create a new record
-k: Create a new set of records from stdin as if piped from show_info -k
-C: Force-copy the storage unit of the original record to the cloned record
-h: Print usage message and exit
-i: Ignore the default behavior of parsing the FITS-file header for keyword values
-m: Modify the keywords of multiple records. The -m flag should be used with caution. A typo could damage many records. Do not use -m unless you are sure the query will specify ONLY the records you want to modify.
-t: Create any needed records as DRMS_TRANSIENT instead of default which is DRMS_PERMANENT
-v: Verbose - noisy.

The -c and -m flags cannot be used simultaneously.

JSOC flags:: DRMS common main program

Usage:

seriesname is the name of the JSOC DRMS series to be updated. If new records are being created, no where clauses are permitted.

record_set A series name followed by a record-set specification (i.e., seriesname[filter]). If record_set resolves to more than one record, then the -m flag must be set to prevent simple typos from doing extensive damage.

Parameters:

	valueN	The new keyword values to be used to create a new or modify an existing record.
	filename	If modifying a record(s) the specified segment is a generic series segment, then first copy the segment file to the cloned record(s)' segment storage, then store the filename with in the segment descriptor. Any leading pathname directories will be removed from the filename value prior to updating the segment descriptor.

Example to modify a keyword value:

set_info ds=su_arta.TestStoreFile[file=dsds_data.fits][sel=January] note=fred

Example to create a new record and specify keyword values:

set_info -c ds=su_arta.TestStoreFile file=data.txt sel=February file_seg=/home/arta/febdata.txt

Bug:

Synopsis:

set_keys [-h] 
set_keys [-ctv] [JSOC_FLAGS] ds=<seriesname> [<keyword>=<value>]... [<segment>=<filename>]...
set_keys [-Cmtv] [JSOC_FLAGS] ds=<record_set> [<keyword>=<value>]... [<segment>=<filename>]...
set_keys_soc {options as above}

Sets keyword values for a record in a DRMS dataseries. set_keys runs in one of two modes.

If the "create" -c flag is present a new record will be created. In this case ALL of the prime keys must be present in keyword=value pairs to specify the locator keywords for the new record. Other keywords and or segments specifications are usually also present.
An existing record_set may be specified and a new version of those record will be made with the specified keywords given new values. Usually, almost always, only a single record is updated in one call of set_keys since only one set of keyword values can be provided and all records modified will be given the same new values for those keywords. If multiple records are to be changed the -m flag is required. set_keys will then clone the records specified by the record-set filter. In the update mode, NONE of the prime keys are allowed in keyword=value pairs on the command line (except of course as a where clause as part of the recordset specification)

For each keyword specified in a keyword=value pair on the command line, set_keys will set the values for all these clones' keywords to value.

If a segment in the series is if type generic then set_keys can be used to store a given file in the SUMS directory associated with the record. In this case, for each segment=filename parameter the file found at filename will be copied into the record directory and the segment filename will be saved in the segment descriptor in DRMS.