Research Division EED/Controls Software<P> Design Note #117.0<P> Epicure Distributed Database System<P> Survey Converter Specification

Research Division EED/Controls Software

Design Note #117.0

Epicure Distributed Database System

Survey Converter Specification

Jith Meganathan

Contents

Revisions

This section lists the revisions that have occurred to the document since the last release.

117.0
July 10, 1992 - Initial release.

Introduction

This document is the design specification for the Survey Converter application. This application is used to populate the central database with location property information about beamline devices.

Survey Converter

The Survey Converter application uses DEC command language interpreter (CLI) files to make DBSA calls. These DBSA calls are then used to place information about beamline devices in the central database. The application may be used to populate the database with information contained in either a single CLI file specified by the user or in multiple CLI files, the names of which are contained in user-defined logicals.

When the Survey Converter application begins, it checks whether the user has provided the name of a single CLI file to be converted. If so, this file is opened for processing. Otherwise, the application must translate a series of logicals in order to obtain the names of the multiple CLI files which it must convert. The application translates each logical in turn, opens the specified file, and processes it. These steps are repeated until every user-defined logical has been translated.

Processing is identical for both single and multiple CLI files, since in both cases, only one file is handled at a time. Each CLI file contains keywords and qualifiers which represent the values of beamline device properties. The Survey Converter application contains routines which are associated with these keywords. When the CLI recognizes a keyword in the file, it calls the corresponding routine in the application. The routine extracts the values contained in the keywords and/or qualifiers and assigns them to a transaction buffer. When an "end-of-device" keyword is recognized, the values in the transaction buffer are committed to the central database. These operations continue until all of the information in the CLI file has been processed.

Using the Survey Converter

The Survey Converter is designed to be used in conjunction with the Survey Retrieval application. However, it can just as easily be used to convert single or multiple CLI files of the user's creation. The first step in using the Survey Converter is to be on the same node and in the same directory as the application. To do this, type: 
        $ set def epicure_root:[work.ecdb.survey.converter]
The only other step necessary is to set-up the project environment by typing: 
        $ @project_setup
Instructions for using the Survey Converter follow.

CLI File Format

For the Survey Converter application to work properly, the CLI file(s) must have the correct format. CLI files created by the Survey Retrieval application will already have this format; this section concerns users who are creating their own CLI files.

A CLI file can include information about multiple devices. Information about each device must contain the following keywords: BEGIN_DEVICE, NAME (followed by the name of a device in the central database), and END_DEVICE. Unless these keywords appear in this order, no device information will be placed in the central database.

The keywords and qualifiers describing device properties must appear between the NAME and END_DEVICE keywords. Currently, only the location property has been defined for beamline devices. The location property for a device may be described by including the keyword LOCATION, followed by a hyphen, or continuation character, in the CLI file. The continuation character indicates that more information about a property is present in the CLI file -- it should be used whenever further qualifiers for a property exist. The qualifiers for the location property are XPOS (x-position), YPOS (y-position), ZPOS (z-position), LENGTH (z-length), PITCH (pitch angle from horizontal), YAW (yaw angle about vertical axis), ROLL (roll angle about beam axis), PREVIOUS (previous device), and NEXT (next device). Each qualifier should appear after the LOCATION keyword, and be preceded by a forward slash (/). If more qualifiers are present, a continuation character is necessary as well. Here is an example of a CLI device definition: 

        BEGIN_DEVICE
       	NAME DEMO2
       	LOCATION-
                /XPOS=2.2-
                /YPOS=2.3-
                /ZPOS=2.4-
                /LENGTH=10.0-
                /PITCH=30.0-
                /YAW=45.62-
                /ROLL=50.23-
                /PREVIOUS=DEMO1-
                /NEXT=DEMO3
        END_DEVICE
Once again, a CLI file can contain multiple device definitions of this type.

Converting One CLI File

Using the Survey Converter on a single CLI file is quite easy if you are on the same node and in the same directory as the Survey Converter application, and your CLI file is properly formatted. To run the application, simply type: 
        $ scvt filename
For example, to use the application on a file named test.dat, enter: 
        $ scvt test.dat
This command will place the information contained within test.dat in the central database as long as you have met the aforementioned conditions.

Note: If the CLI file is not on the same node and in the same directory as the Survey Converter, it will be necessary to specify the file's location when entering its name. For example, if test.dat were located on disney::sys$login, you would need to enter: 

        $ scvt disney::sys$login:test.dat

Converting Multiple CLI Files

In order to use the Survey Converter on multiple CLI files, you must define a logical for each file. The logical must specify the name of the file and, if it is not on the same node and in the same directory as the Survey Converter application, its location. The naming convention used for the logicals is RDCS$SCVT_FILE#, where # is replaced by a 1 for the first CLI file, 2 for the second, and so on. After defining the necessary logicals, simply enter 
        $ scvt
This will cause the Survey Converter to place the information within the CLI files in the central database.

For example, to convert three CLI files, test1.dat, test2.dat, and test3.dat, that are located on disney::sys$login, you would need to enter the following commands: 

        $ define RDCS$SCVT_FILE1 disney::sys$login:test1.dat
        $ define RDCS$SCVT_FILE2 disney::sys$login:test2.dat
        $ define RDCS$SCVT_FILE3 disney::sys$login:test3.dat
        $ scvt
Note: Logicals may be defined on either the process or system tables.

Device Errors Log File

If a CLI file contains information about a device that is not present in the central database, the Survey Converter application will not place the device information in the central database, and instead, will write the device's name to a log file. The log file will be in the same node and directory as the Survey Converter application, and will have the name device_flags.txt. For example, if the CLI file included information about a device named demo4, and this device was not in the database, the log file would read: 
        Device demo4 is not in the database.
The log file can also contain the names of previous and next devices which are not in the central database. For example, if demo4 were listed as a previous device, the log file would read: 
        Previous device demo4 is not in the database.
and if demo4 were listed as a next device, the log file would read: 
        Next device demo4 is not in the database.

Keywords: Epicure, controls, RDCS, database, EDDS

Distribution: normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov