LCLS Channel Archiver Emergency Add PVs

Guidelines For The Use Of This Document

This document describes how to add PVs to the LCLS Channel Archiver system when the primary person responsible for this is unavailable and it is not possible to wait until this person is available. This should happen only rarely. It is preferable to have the person responsible for the LCLS archiver system process requests for changes to archiver configuration files since there are several issues associated with activities such as the addition of new archiver PVs. These are described fully in the "LCLS Channel Archiver Operation" document. A detailed description of the procedure for adding LCLS archiver PVs is also described in that document, which is the primary reference document for the LCLS archvier system. However, this "LCLS Channel Archiver Emergency Add PVs" document fulfills the need of describing this procedure in a simplified "Quick Start" manner.

Overview

There are several LCLS archiver engines and each has an associated XML configuration file. There are typically several thousand archiver PV names in each file. There is a single line in a file for each archiver PV name along with information describing the archiver mode used to archive the PV (monitor or scan) and the interval between samples in seconds (estimated for monitor mode). Each configuration file contains the name of one or more groups used for organization and each group contains one or more archiver PV lines. Briefly, the process of adding PVs to the LCLS archiver consists of the following steps:

  1. Make a list of archiver PVs to add to the LCLS archiver and decide the archiver mode (monitor or scan) that will be used to archive each PV as well as the archive interval between samples in seconds.
  2. For each PV, check whether the PV is already being archived if you have any doubts. Also check to make sure that your list of archiver PV names to add does not contain duplicate names.
  3. Decide which LCLS archive engine configuration file will be edited to add the names of the new archiver PVs. Ideally, the new archiver PV names should belong to an archiver group that has similar PV names (e.g., magnet PV names).
  4. Make a copy of the existing LCLS archiver engine configuration file to be edited before the editing is done. This copy may be used to restart the LCLS archiver engine associated with this file if there is a problem with the edited configuration file (e.g., a typo was introduced).
  5. Edit the chosen LCLS archiver engine configuration file to add the new archiver PV names.
  6. To restart the LCLS archiver engine associated with the edited configuration file, stop this archiver engine process. The LCLS archiver daemon process will automatically restart the archiver engine process after approximately 1-2 minutes if no problem was introduced into the configuration file.
  7. Verify that the LCLS archiver engine process associated with the edited configuration file was restarted.
  8. Verify that the new archiver PVs connected successfully.
Each step will be described briefly.

Step 1: Make list of archiver PVs to add and decide archiver mode and interval

A discussion of archiver modes and a guide to deciding an appropriate archiving interval is beyond the scope of this "quick start" document. Please see the "LCLS Channel Archiver Operation" document for help.

Step 2: Check whether the new archiver PV names to be added are already being archived

There are many thousands of LCLS archiver PV names so a visual inspection is not feasible. A Perl script has been written to check whether each new archiver PV name is already in an archive engine configuration file. However, an alternative for a short list of new archiver PVs is to use a Unix search tool such as "grep", which will be described here.

First, determine the number and names of the current archive engines. This may be done by viewing the LCLS Archive Daemon web page:

LCLS Channel Archiver Archive Daemon Web Page

The archive engine names are in the left column (e.g., LCLS_1, LCLS_2, LCLS_3, LCLS_4, and LCLS_5).

Next, login to the lcls-archsrv machine using the "laci" account or your own account (if permitted). Copy each LCLS archiver configuration file to a temporary directory (the /tmp directory may be used). For the LCLS_1 archive engine configuration file, for example:

The path and file names for the other LCLS archiver configuration files have similar naming structures (e.g., substitute "2" for "1" to copy the LCLS archiver configuration file for the LCLS_2 archive engine).

Finally, use the "grep" utility to search for PV name strings in the list of new archive PV names you made in the archiver configuration XML files. For example, to search for the string "BEND:IN20:231:BACT":

Step 3: Decide which LCLS archive engine configuration file will be edited

This may be a difficult to determine. Each archive engine has a web page that lists all of the group names contained in the engine's configuration file. For example, the web page containing the group names for the LCLS_1 archive engine is:

For the LCLS_2 archive engine, use the number 4902 (adding 1 for each subsequent archive engine).

The goal is to find the most applicable archive engine configuration file to edit for the type of PVs that are being added. For these archive engine web pages, you may select a group name web link to get a listing of the PV names associated with the group. If you are undecided, just pick the archive engine configuration file and group name that seems most reasonable to you and email the person responsible for the LCLS archiver system to inform this person of your choice.

Step 4: Make a copy of the existing LCLS archiver engine configuration file to be edited

If the LCLS_1 archive engine configuration file is to be edited, for example, login to the lcls-archsrv under the laci account and do the following:

  1. cd /arch/lcls/lcls_1
  2. cp lcls_1-group.xml lcls_1-group.xml.old

Step 5: Edit the chosen LCLS archiver engine configuration file to add the new archiver PV names

After step 4 above, your current working directory should be the directory that contains the LCLS archive engine configuration file to be edited. Edit this file using a text editor. Each configuration file contains one or more groups with each group containing one or more XML lines with PV names. You may cut and paste existing XML lines with PV names and then edit these pasted lines. There are 3 items of interest on each XML line that may be edited: (1) the PV name, (2) the archiver mode (either "scan", for the periodic sample mode, or "monitor"), and (3) the sample interval in seconds or, for "monitor" mode, the estimated change rate in seconds.

An example of a XML line with a PV name is:

Step 6: Stop the archiver engine process associated with the edited archiver configuration file

The LCLS Archive Daemon web page referenced above:

LCLS Channel Archiver Archive Daemon Web Page

contains the port numbers associated with the LCLS archive engine processes. For instance, the port number associated with the LCLS_1 archive engine process is 4901. If the archiver configuration file associated with the LCLS_1 archive engine process was edited, the LCLS_1 archive engine process must be then stopped (which will cause this process to be then restarted by the LCLS Archive Daemon process). To stop the LCLS_1 archive engine process through a web browser, enter the following URL

Step 7: Verify that the LCLS archiver engine process associated with the edited configuration file was restarted

To verify that the LCLS archive engine process stopped in the previous step was restarted by the LCLS Archive Daemon process, bring up the LCLS Archiver Daemon web page again:

Monitor the "Status" column on this web page for the archiver engine that was restarted. The "Status" should change from "Not running" to displaying the number of channels (PVs) that are connected out of the total number of channels in the configuration file associated with the archiver engine. Sometimes a message complaining about a lock file appears and then the "Not running" status appears after the next automatic web page update (this web page is updated automatically every 30 seconds). The "Message" section of this web page indicates when archive engines were restarted by the LCLS Archive Daemon process.

If this web page does not indicate that the stopped archive engine process was restarted successfully after approximately 3 minutes, it is likely that there is a problem in the edited configuration file associated with this process (probably a typo). In this case, save your edited file by copying it to another file and restore the configuration file using the copy of the file before the editing change you made in step 4. If the LCLS_1 archive engine configuration file was edited, for example, login to the lcls-archsrv under the laci account and do the following:

  1. cd /arch/lcls/lcls_1
  2. cp lcls_1-group.xml lcls_1-group.xml.bad
  3. cp lcls_1-group.xml.old lcls_1-group.xml

Step 8: Verify that the new archiver PVs connected successfully

To verify that the new archiver PVs connected successfully, bring up the web page for the archiver group for which PVs were added. First, bring up the groups web page for the archive engine associated with the edited archiver configuration file. For example, if the configuration file for the LCLS_1 archiver engine was edited:

This web page indicates the total number of channels (PVs) in each archiver group and the number that are currently connected. On this web page, select the blue web link for the archiver group for which PVs were added (an example for the LCLS_1 archiver engine is the lcls_1_slc group). This will display archiver information about channel (PV) in this archiver group. The "State" column will be red for channels that are not connected. If the "State" column is red for one or more of the PVs that you added to the group, check the PV name to make sure there is not a typo mistake before checking the state of the PV (using the EPICS tools "caget" or "camonitor", for example).

Author:  Bob Hall 15-Dec-2008