EPICS V4 Directory Service

Version 0.5.0-SNAPSHOT, 07-Nov-2012

Editors:
Ralph Lange, ITER Organization

Abstract

This is a reference implementation of the EPICS V4 Directory Service. It uses the following parts of the EPICS V4 framework:

pvData
pvData (Process Variable Data) defines and implements an efficent way to store, access, and transmit memory resident structured data
pvAccess
pvAccess is network support for transmitting pvData.
pvService
A middle layer for implementing services.

The EPICS V4 Directory Service is built on top of the ChannelFinder Directory Service, and uses both the web service and its Java API Client library.

Status of this Document

This documents the 07-Nov-2012 version of the EPICS V4 Directory Service. This release implements both the service and an example command line client, as standalone Java applications.

TODO

The following is a list of unresolved issues for Directory Service:

example directory data
The release should contain sample directory data covering the channels contained in the example.

Table of Contents

Introduction

EPICS V4 Directory Service is a V4 query interface to ChannelFinder, allowing applications to make ChannelFinder queries and receive the results using pvAccess.

This package provides a single service:

ds
This service takes a query and arguments in an NTURI structure, executes the appropriate request through ChannelFinder's web service, and returns the result as an NTTable structure.

pvAccess Structure Formats

Request (NTURI)

The client sends the request as an NTURI structure.

The following fields are recognized:

query (mandatory)
The ChannelFinderAPI query string: Space separated search criteria, patterns may include * and ? wildcards.
channelNamePattern propertyName=valuePattern1,valuePattern2 Tags=tagNamePattern
Each criteria is logically ANDed, || separated values are logically ORed.
Example: SR* Cell=1,2 Tags=GoldenOrbit,myTag
This will return all channels with names starting with SR AND having property Cell=1 OR 2 AND having tags goldenOrbit AND myTag.
IMP: each criteria is logically ANDed, while multiple values for properties are ORed.
show
Comma separated list of properties and tags to include (as columns) in the result.
sort
Comma separated list of properties and tags to sort the result channels (lines) by.
owner
When set, the result will contain a column showing the channel owner.

Result (NTTable)

The server returns the result as an NTTable structure.

Each channel in the result is represented by one line of the table.

The first column contains the channel name, the second column contains the channel owner (if owner was specified in the request). The following columns contain properties and tags of the channels, with the column labels being set to the property or tag names. If show was specified in the request, the order of result columns matches the order specified in the request.

Running the Service

Prerequisites

You need a running instance of the ChannelFinder web service. Please refer to the ChannelFinder installation instructions to find out how to set this up.

For the ChannelFinder client library inside the V4 Directory Service, you will have to supply a preference file that specifies the URL of the ChannelFinder web service. In the home directory of the user running the service, create a file named channelfinder.properties that contains a line like

channelfinder.serviceURL=http://localhost:8080/ChannelFinder

pointing to the URL of your ChannelFinder web service instance.

Distribution Tar

The distribution tar is complete, and includes all necessary dependencies. You can unpack it and run the service at any location in your file system.

Service

The service is started using the dsServiceRunner script in the bin directory of the distribution. This script does not take arguments.

Dedicated Command Line Client

The client is started using the dsClientRunner script in the bin directory of the distribution. It understands the following arguments:

query=<query string>
The ChannelFinderAPI query string: Space separated search criteria, patterns may include * and ? wildcards.
channelNamePattern propertyName=valuePattern1,valuePattern2 Tags=tagNamePattern
Each criteria is logically ANDed, || separated values are logically ORed.
Example: SR* Cell=1,2 Tags=GoldenOrbit,myTag
This will return all channels with names starting with SR AND having property Cell=1 OR 2 AND having tags goldenOrbit AND myTag.
IMP: each criteria is logically ANDed, while multiple values for properties are ORed.
query= can be omitted if this is the first argument.
show=<list>
Comma separated list of properties and tags to include (as columns) in the result.
sort=<list>
Comma separated list of properties and tags to sort the result channels (lines) by.
owner
When set, the result will contain a column showing the channel owner.
nolabels
When set, no column labels will be printed.

Examples

This shows a query (against a BNL example directory database) using the dedicated client:

> ./dsClientRunner "SR:C01-MG:G04* Tags=aphla.sys.V1SR" show=devName,sEnd,length sort=length,sEnd                                            
             channel               devName     sEnd   length 
  SR:C01-MG:G04A{HFCor:FM1}Fld-SP  FM1G4C01A  37.8822   0.044
   SR:C01-MG:G04A{HFCor:FM1}Fld-I  FM1G4C01A  37.8822   0.044
   SR:C01-MG:G04A{VFCor:FM1}Fld-I  FM1G4C01A  37.8822   0.044
  SR:C01-MG:G04A{VFCor:FM1}Fld-SP  FM1G4C01A  37.8822   0.044
      SR:C01-MG:G04A{VCor:M}Fld-I  SQMG4C01A  36.7222     0.2
      SR:C01-MG:G04A{HCor:M}Fld-I  SQMG4C01A  36.7222     0.2
   SR:C01-MG:G04A{SQuad:M1}Fld-SP  SQMG4C01A  36.7222     0.2
    SR:C01-MG:G04A{SQuad:M1}Fld-I  SQMG4C01A  36.7222     0.2
     SR:C01-MG:G04A{VCor:M}Fld-SP  SQMG4C01A  36.7222     0.2
     SR:C01-MG:G04A{HCor:M}Fld-SP  SQMG4C01A  36.7222     0.2
     SR:C01-MG:G04A{Sext:M1}Fld-I  SM1G4C01A  37.7322     0.2
    SR:C01-MG:G04A{Sext:M1}Fld-SP  SM1G4C01A  37.7322     0.2
     SR:C01-MG:G04B{Sext:M1}Fld-I  SM1G4C01B  40.2722     0.2
    SR:C01-MG:G04B{Sext:M1}Fld-SP  SM1G4C01B  40.2722     0.2
     SR:C01-MG:G04A{Quad:M1}Fld-I  QM1G4C01A  37.3322    0.25
    SR:C01-MG:G04A{Quad:M1}Fld-SP  QM1G4C01A  37.3322    0.25
    SR:C01-MG:G04B{Sext:M2}Fld-SP  SM2G4C01B  39.1022    0.25
     SR:C01-MG:G04B{Sext:M2}Fld-I  SM2G4C01B  39.1022    0.25
    SR:C01-MG:G04B{Quad:M1}Fld-SP  QM1G4C01B  40.8722    0.25
     SR:C01-MG:G04B{Quad:M1}Fld-I  QM1G4C01B  40.8722    0.25
    SR:C01-MG:G04A{Quad:M2}Fld-SP  QM2G4C01A  38.6687   0.283
     SR:C01-MG:G04A{Quad:M2}Fld-I  QM2G4C01A  38.6687   0.283
     SR:C01-MG:G04B{Quad:M2}Fld-I  QM2G4C01B  39.5687   0.283
    SR:C01-MG:G04B{Quad:M2}Fld-SP  QM2G4C01B  39.5687   0.283
    SR:C01-MG:G04B{HCor:M1}Fld-SP  CM1G4C01B  41.2812     0.3
     SR:C01-MG:G04B{HCor:M1}Fld-I  CM1G4C01B  41.2812     0.3
    SR:C01-MG:G04B{VCor:M1}Fld-SP  CM1G4C01B  41.2812     0.3
     SR:C01-MG:G04B{VCor:M1}Fld-I  CM1G4C01B  41.2812     0.3

This is the same query using the generic eget client:

> ../../pvAccessCPP/bin/linux-x86_64/eget -s ds -a query="SR:C01-MG:G04* Tags=aphla.sys.V1SR" -a show=devName,sEnd,length -a sort=length,sEnd 
                          channel                          devName                             sEnd                           length
  SR:C01-MG:G04A{HFCor:FM1}Fld-SP                        FM1G4C01A                          37.8822                            0.044
   SR:C01-MG:G04A{HFCor:FM1}Fld-I                        FM1G4C01A                          37.8822                            0.044
   SR:C01-MG:G04A{VFCor:FM1}Fld-I                        FM1G4C01A                          37.8822                            0.044
  SR:C01-MG:G04A{VFCor:FM1}Fld-SP                        FM1G4C01A                          37.8822                            0.044
      SR:C01-MG:G04A{VCor:M}Fld-I                        SQMG4C01A                          36.7222                              0.2
      SR:C01-MG:G04A{HCor:M}Fld-I                        SQMG4C01A                          36.7222                              0.2
   SR:C01-MG:G04A{SQuad:M1}Fld-SP                        SQMG4C01A                          36.7222                              0.2
    SR:C01-MG:G04A{SQuad:M1}Fld-I                        SQMG4C01A                          36.7222                              0.2
     SR:C01-MG:G04A{VCor:M}Fld-SP                        SQMG4C01A                          36.7222                              0.2
     SR:C01-MG:G04A{HCor:M}Fld-SP                        SQMG4C01A                          36.7222                              0.2
     SR:C01-MG:G04A{Sext:M1}Fld-I                        SM1G4C01A                          37.7322                              0.2
    SR:C01-MG:G04A{Sext:M1}Fld-SP                        SM1G4C01A                          37.7322                              0.2
     SR:C01-MG:G04B{Sext:M1}Fld-I                        SM1G4C01B                          40.2722                              0.2
    SR:C01-MG:G04B{Sext:M1}Fld-SP                        SM1G4C01B                          40.2722                              0.2
     SR:C01-MG:G04A{Quad:M1}Fld-I                        QM1G4C01A                          37.3322                             0.25
    SR:C01-MG:G04A{Quad:M1}Fld-SP                        QM1G4C01A                          37.3322                             0.25
    SR:C01-MG:G04B{Sext:M2}Fld-SP                        SM2G4C01B                          39.1022                             0.25
     SR:C01-MG:G04B{Sext:M2}Fld-I                        SM2G4C01B                          39.1022                             0.25
    SR:C01-MG:G04B{Quad:M1}Fld-SP                        QM1G4C01B                          40.8722                             0.25
     SR:C01-MG:G04B{Quad:M1}Fld-I                        QM1G4C01B                          40.8722                             0.25
    SR:C01-MG:G04A{Quad:M2}Fld-SP                        QM2G4C01A                          38.6687                            0.283
     SR:C01-MG:G04A{Quad:M2}Fld-I                        QM2G4C01A                          38.6687                            0.283
     SR:C01-MG:G04B{Quad:M2}Fld-I                        QM2G4C01B                          39.5687                            0.283
    SR:C01-MG:G04B{Quad:M2}Fld-SP                        QM2G4C01B                          39.5687                            0.283
    SR:C01-MG:G04B{HCor:M1}Fld-SP                        CM1G4C01B                          41.2812                              0.3
     SR:C01-MG:G04B{HCor:M1}Fld-I                        CM1G4C01B                          41.2812                              0.3
    SR:C01-MG:G04B{VCor:M1}Fld-SP                        CM1G4C01B                          41.2812                              0.3
     SR:C01-MG:G04B{VCor:M1}Fld-I                        CM1G4C01B                          41.2812                              0.3