show_info - Examine a dataseries structure or contents
[DRMS Utilities]

Collaboration diagram for show_info - Examine a dataseries structure or contents:

Synopsis:

show_info -j {ds=}<seriesname>
show_info -l {ds=}<seriesname>
show_info -c {ds=}<record_set>
show_info -s {ds=}<seriesname>
show_info [-aAbiIKoOpPrRSTvxz] [-dkqt] {ds=}<record_set>|sunum=<sunum> [n=<count>] [key=<keylist>] [seg=<seglist>]
show_info_sock {same options as above}

Show_info shows various kinds of information about a data series. This can be the series structure, the "jsoc series definition" for the series, all or some of the keyword and segment values for a range of records, the full path to the SUMS storage for the data segment, etc. Exactly what information gets printed is controlled by command-line flags (see below).

By default, show_info will time-out on long-running database queries after a 10-minute wait. If -O is provided on the command-line, the time-out is disabled. Both of these behaviors are overridden the by DRMS_DBTIMEOUT cmd-line argument.

The argument descriptions are grouped by function. The first group controls the overall operation of show_info. If any of these flags (c,h,j,l,s) is present the specified action is taken and the program exits. Otherwise a DRMS query is made and the resulting records are examined and the specified quantities are printed for each record found. If the QUERY_STRING argument is present it is parsed to extract command line arguments passed via a web cgi-bin call of show_info and the results are returned as text.

show_info_sock is the same as show_info but configured to run in a DRMS session via a socket connection to a drms_server session (see e.g. drms_run).

Options:

Flags controling operation to perform:

This group of arguments controls the action of show_info. The default action is to query for the specified record-set and perform the requested display of information.

• -c: Show count of records in query and exit. This flag requires a record set query to be specified.
• -e: Parse the provided record-set query into constituent parts (e.g., "hmi.M_45s[2013.1.8][? QUALITY > 0 ?]" --> "hmi.M_45s" "[2013.1.8][? QUALITY > 0 ?]"
• -h: help - print usage info and exit
• -j: list series info in jsd format and exit
• -l: just list series keyword, segment, and link names with descriptions then exit
• -s: stats - show some statistics about the series, presently only first and last record.
• QUERY_STRING=<cgi-bin GET format command line args> - string with default "Not Specified" used when show_info is invoked from http://jsoc.stanford.edu/cgi_bin/ajax/show_info

Parameters and Flags controling record subset to examine:

This group of arguments specifies a recordset to examine. If the "sunum" argument is present it overrides an explicit recordset specification and returns the record with that sunum as its record directory pointer in SUMS. For normal recordset queries the "ds=" is optional. In no "where clauses" (i.e. "[xxx]" clauses) are present in the recordset query the "n" parameter is required. Since the "where clauses" are used to restrict the number or records retrieved, an empty clause (e.g. "[]") will match all records in the series.

• ds= <record_set query>=""> - string with default "Not Specified", see below for more information.
• sunum= <sunum> - integer with default -1, overrides a "ds" specification.
• n= <count> - Max number of records to show, +from first, -from last, see below.

Parameters and Flags controling selction of keywords and segments to examine:

This group of arguments specifies the set of keywords, segments, links, or virtual keywords to display.

• key= <keylist> - string with default "Not Specified", see below.
• seg= <seglist> - string with dedfauly "Not Specified", see below.
• -a: Select all keywords and display their values for the chosen records
• -A: Select all segments and display their filenames/paths/dimensions for the chosen records
• -b: Disable the prime-key logic when opening records (implicitly adds the [! 1=1 !] to the record-set specification)
• -i: print record query, for each record, will be before any keywwords or segment data
• -I: print session information including host, sessionid, runtime, jsoc_version, and logdir
• -K: Select all links and display their targets for the chosen records
• -o: list the record's online status
• -O: disable the code that sets a database query time-out of 10 minutes
• -p: list the record's storage_unit path, waits for retrieval if offline
• -P: list the record\'s storage_unit path but no retrieve
• -r: recnum - show record number as first keyword
• -R: retention - show the online expire date for the segment data
• -S: SUNUM - show the sunum for the record
• -T: Tape - show the archive tape name for the record
• -v: verbose - print extra, helpful information
• -x: archive - show archived flag for the storage unit.
• -z: SUNUM - show the storage unit size for the SU that contains the record's segments

Flags controling how to display values:

• -d: Show dimensions of segment files with selected segs
• -k: keyword list one per line
• -q: quiet - skip header of chosen keywords
• -t: types - show types and print formats for keyword values

JSOC flags:

DRMS common main program

Usage:

seriesname A seriesname is a JSOC DRMS seriesname. It is the prefix of a record_set specification.

record_set A record_set list is a comma separated list of record_set queries. Each query is a series name followed by an optional record-set specification (i.e., seriesname[RecordSet_filter]). Causes selection of a subset of records in the series. This argument is required, and if no record-set filter is specified, then n=nrecords must be present. The "ds=" protion of the record_set argument is optional.

sunum Instead of providing a normal record_set query an explicit storage unit id (sunum) may be provided. In this case the provided sunum will be found in the SUMS tables and the parent series will be queried for the record owning the specified sunum. The "Prime-Key" logic does not apply in this case (the "[! ... !]" form of a general query clause is used) so the matching record may not be the latest version.

count specifies the maximum number of records for which information is printed. If count < 0, show_info - Examine a dataseries structure or contents displays information for the last count records in the record set. If count > 0, show_info - Examine a dataseries structure or contents displays information for the first count records in the record set. If record_set contains a record set filter, then count applies to the set of records matching the filter.

keylist Comma-separated list of keyword names. For each keyword listed, information will be displayed. keylist is ignored in the case that the -a flag is set.

seglist Comma-separated list of segment names. seglist is ignored in the case that the -A flag is set. For each segment listed, the segment's file is displayed. If the -p flag is set the filename will be prefaced by the full path to the file in SUMS. If the storage unit containing the record directory is offline, it will be staged first and the new online location is reported. If the -P flag is given the path is displayed only if the data is online. If offline with a -P flag then only the filename is shown. If the -d flag is set then the dimensions of the segment array are displayed along with the path/filename.

Warning:

NOTE to the csh user, you need to excape the '[' character and some other characters used in the record set specification.

Output:

In the normal table mode, show_info presents keyword and segment values in a table with a column for each keyword, segment, or other quantity and a row for each record in the selected record_set. The columns are tab separated. Unless the -q flag is present a header row(s) will be provided. The normal header is a single row containing the column name. If the -t flag is present an expanded header will contain three lines: the normal name list line, a second line containing the type of the values, e.g. int, double, etc. and a third line containing the type as a printf printing format, e.g. s for a string.

In the keyword format, invoked with a -k flag, there is one name=

pair per line. Lines for each record are preceeded with a line beginning with a '#' and containing the record_set query that finds that record and followed by a single blank line.

The -q flag is provided to make it convenient to use the output of show_info in scripts. Example 3 below shows such a usage.

Note about DRMS_RETENTION flag:

If show_info is used to modify the retention time or one or more storage units, you must call show_info in a way that it makes a SUMS request. The easiest way to do this is to call it with the -P flag. Retention can be reduced only if the caller is the owner of the database "series" table (the table whose name is also the name of the series).

Examples:

Example 1: To show the storage-unit paths for a maximum of 10 records:

  show_info -p ds=su_arta.TestStoreFile n=10

Example 2: To show information, in non-table format, for all keywords, plus the segment named file_seg and storage unit number, for a maximum of 10 records:

  show_info ds=su_arta.TestStoreFile -akrS n=10 seg=file_seg

Example 3: To find the path to the most recent hmi level-0 small image and start the ds9 display program:

  ds9 `show_info -q -p seg=image_sm 'hmi.lev0e[:#$]'`

Example 4: To show the structure of a series:

  show_info -l su_phil.vw_V_mean

Bug:

SHOW_INFO WILL NOT WORK PROPERLY IF THE RECORD-SET STRING SPECIFIES MORE THAN ONE SERIES.

See also:

http://jsoc.stanford.edu/ajax/lookdata.html drms_query - for each record specified, print the psql 'recnum' value, and optionally the record-directory path describe_series - print summary information about a series jsoc_info - same as show info, except that can output json and run under cgi-bin create_series - create a new DRMS series from a .jsd file