Command Line Interface

Briefly

Below there is an DBEL help from console veriosn

usage: java -jar DBEL.jar <measurementName1  ...  measurementNameN> -a | -c  <columnNames> | -h  [-d] [-f <firstResultNumber>]  [-i1 <beginIntervalOfValidity>] [-i2 <endIntervalOfValidity>] [-n <numberOfResults>] [-o <outputFile>] [-p <password>] [-r <runNumber>] [-t1 <beginTimestamp>] [-t2 <endTimestamp>] [-u <user>] [-v]

Command Line Interface for TOTEM DataBase Extraction Library
 -a,--all                                    Retrieving whole row as  object
 -c,--columns <columnNames>                  Retrieving selected columns: ID, TYPE, TIMESTAMP, IOV,  SINGLE_VALUE, VECTOR_VALUE
 -d,--description                            Description of the query
 -f,--first <firstResultNumber>              First result number (int)
 -h,--help                                   Help
 -i1,--iov_begin <beginIntervalOfValidity>   Begin interval of validity  (yyyy/mm/dd hh:mm:ss,microsec)
 -i2,--iov_end <endIntervalOfValidity>       End interval of validity  (yyyy/mm/dd hh:mm:ss,microsec)
 -n,--number <numberOfResults>               Number of results (int)
 -o,--ouput <outputFile>                     Path to output file
 -p,--password <password>                    Access password
 -r,--runNumber <runNumber>                  Run number
 -t1,--timestamp_begin <beginTimestamp>      Begin timestamp (yyyy/mm/dd hh:mm:ss,microsec)
 -t2,--timestamp_end <endTimestamp>          End timestamp (yyyy/mm/dd  hh:mm:ss,microsec)
 -u,--user <user>                            Access login
 -v,--verbose                                Display all informaion about the query
 -vv,--veryVerbose                           Printing stacktrace when error occured

Requirements

There are what you need to run DBEL console version:

• JRE (Java Runtime Environment) available to download from http://java.com/en/download/
• cli.properties (described below)

Help

To get help about using the DBEL console application, the following options should be used

 -h,--help                                   Help

Configuration

Before using DBEL console application user should configure environment. To use DBEL user should create in the same folder as dbel.jar the file named cli.properties and put inside one line:

dbel.host=[server_host]\:[server_port]

In the field "server_host" user must put address of the server, eg. pctotem30.cern.ch, and in the field "server_port", the http port on which the server application is running, eg. 8888 (Tomcat default 8080).

Moreover user can specified in this file the rest of credentials: username and password, it is not necessary, but recommended. DBEL uses CERN authentication system. So to use this application you must have CERN NICE login and password. In cli.properties user should put following two lines:

dbel.user=[CERN_NICE_login]
dbel.pass=[CERN_NICE_password]

replacing "CERN_NICE_login" and "CERN_NICE_password" with user's own login and password. Example of cli.properties

• without specifying login and password:

dbel.host=pctotem30.cern.ch\:8888

• with specifying login and password:

dbel.host=pctotem30.cern.ch\:8888
dbel.user=john_smith
dbel.pass=my_password

Usage

DBEL console application is supplied as JAR archive, so to run dbel.jar user should use the following syntax (Java Runtime Environment is necessary):

java -jar dbel.jar

Then should be given names of measurements (listed in names.xml on Twiki pages of DBEL). This could be one measurement or more (without any separators). If there is no measurement with given name in database, the result set will be deprived of such measurement. Next user should select one of the options -a and -c, and at the end the rest of options (all described below).

Result set

See first general information about result set

DBEL application allows users to choose which information to include in the output file. This is made possible by the following options:

• -a,--all - it retrieves all data about the measurements
• -c,--columns <columns> - it allows to specify what kind of data user want to have in output xml file; possible options for columns (using without any separators) are:
  • ID (Identifier)
  • IOV (Interval of Validity)
  • TIMESTAMP (Timestamp)
  • SINGLE_VALUE and VECTOR_VALUE (Value)

Using one of these options is required by the application. If user specifies Interval of Validity or Type of Measurement to put in output file, all data describing this information will be included.

Time range

See first general information about time range

For specifying time range there are following parameters of DBEL:

 -i1,--iov_begin <beginIntervalOfValidity>   Begin interval of validity (yyyy/mm/dd hh:mm:ss,microsec)
 -i2,--iov_end <endIntervalOfValidity>       End interval of validity (yyyy/mm/dd hh:mm:ss,microsec)
 -t1,--timestamp_begin <beginTimestamp>      Begin timestamp (yyyy/mm/dd hh:mm:ss,microsec)
 -t2,--timestamp_end <endTimestamp>          End timestamp (yyyy/mm/dd  hh:mm:ss,microsec)

Time formats:

• yyyy - 4-digit format for year
• mm - 2-digit format for month (01-12)
• dd - 2-digit format for day (01-31)
• hh - 24 hours format (00-23)
• mm - minutes (00-59)
• ss - seconds (00-59)
• microseconds - must be given in three-digit format.

Number of results

See first general information about number of results

In order to specify number of results user can use paramater:

 -n,--number <numberOfResults>               Number of results (int)

This option limits the result set of measurements to given numberOfResults.

To specify first result number there is an option:

 -f,--first <firstResultNumber>              First result number (int)

This will skip the firstResultNumber measurements from the measurements retrieved from database (omission given number measurements in the result set, counting from beginning of result set).

Description

See first general information about description

In order to put description into output file user should use option:

 -d,--description                            Description of the query

To see the query that was specified, but not put it into the output XML file, user should option:

 -v,--verbose                                Display all informaion about the query

This option prints all the information about the query on the console.

For debug veru useful can be the following option:

 -vv,--veryVerbose                           Printing stacktrace when error occured

When error occure this will print Java stacktrace. Note that this option doesn't print information, which are provided bu -v.

Above options can be used simultaneously.

Output

The default output is console. But in many cases preferred are XML files. To specify output XML file user should option:

 -o,--ouput <outputFile>                     Path to output file

This create given file and redirect default output into this file.

Credentials

As it was said in first chapter, CERN NICE username and password should be specified in the file cli.properties. But if for some reason (eg. security) user do not want to store credentials in the config file, they can be specified using the following options:

 -p,--password <password>                    Access password
 -u,--user <user>                            Access login

If user specify credentials using these options, but credentials are also stored in cli.properties, the specified by console will be use. It's because the credentials from the config file have a lower priority.

Examples

---

---

Example #1

We want to get data about measurements: LHC.BOFSU:POS_ERR_H and LHC.BOFSU:POS_ERR_V, only 2 results, all data about measurements, we want to be informaed about our query

Input

java -jar DBEL.jar LHC.BOFSU:POS_ERR_H LHC.BOFSU:POS_ERR_V -a -n 2 -v

Output

Username:   jszymane
Measurements: 
   LHC.BOFSU:POS_ERR_H
   LHC.BOFSU:POS_ERR_V
Begin timestamp: unspecified
End timestamp: unspecified
Begin interval of validity: unspecified
End interval of validity: unspecified
Number of results: 2
First result number: unspecified
Output: console
Description: no
Verbose: yes
Data: whole row

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Results>
    <rows>
        <row xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="T18GeneralMeasurement" t18GeneralMeasId="13382932">
            <t15MeasurementType t15MeasurementId="91">
                <measurementName>LHC.BOFSU:POS_ERR_H</measurementName>
                <measurementSingleUnit>mm</measurementSingleUnit>
                <measurementDescription>Beam position measurement errors in horizontal plane.</measurementDescription>
                <measurementColumnDescription>
                    <item value="BPMSW.1R1.B1" id="0"/>
                    <item value="BPMS.2R1.B1" id="1"/>
                    <item value="BPMSY.4R1.B1" id="2"/>
                    <item value="BPMWB.4R1.B1" id="3"/>
                    <item value="BPMYA.4R1.B1" id="4"/>
                    <item value="BPM.5R1.B1" id="5"/>
...
        </measurementColumnDescription>
            </t15MeasurementType>
            <t3ValidityInterval t3IovId="625933">
                <startTime>2010-11-09 19:03:52.172</startTime>
                <endTime>2010-11-09 19:03:53.172</endTime>
            </t3ValidityInterval>
            <measurementTimestamp>2010-11-09 19:03:52.172</measurementTimestamp>
            <measurementValue>
                <item value="11.4101886909857" id="0"/>
                <item value="11.2739364951572" id="1"/>
                <item value="9.55541676194945" id="2"/>
                <item value="12.69967376939" id="3"/>
                <item value="9.9279446738375" id="4"/>
                <item value="10.2673059339253" id="5"/>
...
     </measurementValue>
        </row>
        <row xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="T18GeneralMeasurement" t18GeneralMeasId="13382400">
            <t15MeasurementType t15MeasurementId="90">
                <measurementName>LHC.BOFSU:POS_ERR_V</measurementName>
                <measurementSingleUnit>mm</measurementSingleUnit>
                <measurementDescription>Beam position measurement errors in vertical plane.</measurementDescription>
                <measurementColumnDescription>
                    <item value="BPMSW.1R1.B1" id="0"/>
                    <item value="BPMS.2R1.B1" id="1"/>
                    <item value="BPMSY.4R1.B1" id="2"/>
                    <item value="BPMWB.4R1.B1" id="3"/>
                    <item value="BPMYA.4R1.B1" id="4"/>
                    <item value="BPM.5R1.B1" id="5"/>
...

---

---

Example #2

We want to to get data about measurement HX:ENG, begining from 2011/07/06 15:16:17,18, as previous only 2 results, include description, but data should include only IDa nd value

Input

java -jar DBEL.jar HX:ENG -c ID SINGLE_VALUE  -t1 2011/07/06 15:16:17,18 -n 2 -d

Output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Results>
    <description>
        <lowerTimestamp>2011-07-06 15:16:17.18</lowerTimestamp>
        <projectionColumns>
            <item value="t18GeneralMeasId" id="0"/>
            <item value="measurementSingleValue" id="1"/>
        </projectionColumns>
        <maxResults>2</maxResults>
        <measurementNames>
            <item value="HX:ENG" id="0"/>
        </measurementNames>
    </description>
    <rows>
        <row xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="T18GeneralMeasurement" t18GeneralMeasId="20271841">
            <measurementSingleValue>29168</measurementSingleValue>
        </row>
        <row xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="T18GeneralMeasurement" t18GeneralMeasId="20271839">
            <measurementSingleValue>29168</measurementSingleValue>
        </row>
    </rows>
</Results>

---

---

Example #3

We want to to get data about measurement type: LHC.BOFSU:POS_ERR_H, all kinds of data, from run number 2, without description.

Input

java -jar DBEL.jar  LHC.BOFSU:POS_ERR_H -a -r 2

Output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Results>
    <rows>
        <row xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="T18GeneralMeasurement" t18GeneralMeasId="13382932">
            <t15MeasurementType t15MeasurementId="91">
                <measurementName>LHC.BOFSU:POS_ERR_H</measurementName>
                <measurementSingleUnit>mm</measurementSingleUnit>
                <measurementDescription>Beam position measurement errors in horizontal plane.</measurementDescription>
                <measurementColumnDescription>
                    <item value="BPMSW.1R1.B1" id="0"/>
                    <item value="BPMS.2R1.B1" id="1"/>
                    <item value="BPMSY.4R1.B1" id="2"/>
                    <item value="BPMWB.4R1.B1" id="3"/>
                    <item value="BPMYA.4R1.B1" id="4"/>
                    <item value="BPM.5R1.B1" id="5"/>
...
                </measurementColumnDescription>
            </t15MeasurementType>
            <t3ValidityInterval t3IovId="625933">
                <t4RunTimelineMap t4RunId="161">
                    <runNumber>2</runNumber>
                    <firstEventNo>1</firstEventNo>
                    <lastEventNo>90000</lastEventNo>
                    <firstEventTime>2009-09-20T00:00:00+02:00</firstEventTime>
                    <lastEventTime>2009-09-20T00:00:00+02:00</lastEventTime>
                    <description>Very interesting run, from Zurich to Geneve</description>
                </t4RunTimelineMap>
                <startTime>2010-11-09 19:03:52.172</startTime>
                <endTime>2010-11-09 19:03:53.172</endTime>
            </t3ValidityInterval>
            <measurementTimestamp>2010-11-09 19:03:52.172</measurementTimestamp>
            <measurementValue>
                <item value="11.4101886909857" id="0"/>
                <item value="11.2739364951572" id="1"/>
                <item value="9.55541676194945" id="2"/>
                <item value="12.69967376939" id="3"/>
                <item value="9.9279446738375" id="4"/>
                <item value="10.2673059339253" id="5"/>
...

---

---

-- JakubSzymanek - 02-Sep-2011