RD/Controls Software Release Note 94.1 <P> SWICALL - A Program to Collect and Format SWIC Data

RD/Controls Software Release Note 94.1

SWICALL - A Program to Collect and Format SWIC Data

Thomas R. Kobilarcik

RD/SOD Ops

Fri Mar 29 10:32:40 CST 1996

Introduction

SWICALL is a program designed to collect raw SWIC data and reformat the data for display and analysis. The reformatted data is written to files corresponding to the SWIC name, current date, and data type. The program may be run in three ``modes'':

  1. directly from the command line (``External Driven Mode'').
  2. from an EPICURE style menu, with parameters read from a user-chosen file (``File Driven Mode'').
  3. from an EPICURE style menu, with parameters entered from the menu (``Menu Driven Mode'').
Raw data may be reformatted into any of three forms:
  1. floating-point data ( .DAT file).
  2. VAX/UIS graphics display ( .UIS file).
  3. ASCII character graphics display ( .TXT file).
This document will explain how to run SWICALL in each mode, how to interpret filenames and types produced by SWICALL, and outline other features of the program.

Running SWICALL

Common Features

In order to use all features of SWICALL, you must install a ``foreign command'' by typing the following:

Now, in order to run SWICALL, you need only type TESTP. Try it!

The first thing you will notice is the following block of data:

   USR\$DISK1:[KOBILARCIK.EPICURE]SWICALL.C;126 -- v4.3
   Compiled Feb 11 1991 14:27:16
   command[0] -> daffy\$dub1:[kobilarcik.epicure]swicall.exe;160
   info[0] -> PATH=usr\$disk1:["your current account"]
   info[1] -> HOME=usr\$disk1:["your default directory"]
   info[2] -> TERM="terminal you are at now"
   info[3] -> USER="your user name"
This information is used by SWICALL to determine the running mode.

Menu Driven Mode

Begin by typing TESTP. The above information will flash on the screen. Next, the typical EPICURE menubar will pop up. Choose SETUP. A dialog box will prompt you for the SWIC name. After entering the SWIC name, the name will be rewritten below the box, and a new box will prompt you regarding a ``text file.'' Again, your answer is echoed below the box. Next, you will be asked if you want the scans displayed, then if you wish SWICALL to create a data file, and finally if you wish SWICALL to print the scans to the companion printer.

You may enter up to fourteen SWICs in menu driven mode. After the fourteenth SWIC, you will be kicked back to the menubar. If you attempt to enter more SWICs, all previous information will be erased.

Now, choose RUN. As SWICALL collects data and creates files, messages will be displayed along the right side of the screen, in order to keep you posted on the progress of the program. If there are errors in the system, program, or data, the error messages will appear on the same line as the SWIC name.

When FINISHED appears in the upper right hand corner, SWICALL in finished. You may exit, run again with the same parameters, or enter new parameters.

File Driven Mode

When you run SWICALL in file driven mode, the program reads a list of SWIC names from a file. So, you must make your own text file, copy, or direct SWICALL to use someones file. Please note that in file driven mode, all options are chosen, unless an entire class is disabled.

Creating the Input File

The proper format for the text file is a list of SWIC names, separated by carriage returns. You may also include blank lines and whitespace - the program will ignore these. For example, you may make the file SWIC.NAMES as follows:

N00wcs
<tab>nE1Wc1S
<line>
<space>P03wc
<line>
M00wc1S
Note that you do not have to worry about case or even correct device names! SWICALL converts all names into upper case and ignores bad devices.

Up to 120 devices may be entered in this mode. If there are more devices, everything after device 120 will be ignored. Unfortunately, bad devices count in these 120 devices, so if you find mistakes, correct your list!

Running in File Driven Mode

Begin by typing TESTP. A block of information will flash on the screen, then the typical EPICURE menu will appear. This time, choose FILE. You will be prompted for a file name. Enter the name of the file you just created, or the name of someone elses file (feel free to look in my directory for file names). Remember, if you select someone elses file, provide the complete VMS path name to that file!

Next, choose RUN. SWICALL will begin collecting data from the SWICs in the input file. As in Menu Driven Mode, messages will appear to the right of the SWIC names as file are created or errors are encountered. When the bottom of the display is reached, SWICALL will begin writing new information at the top.

When FINISHED appears in the upper right hand corner, SWICALL is finished. You may exit, run again with the same parameters, or enter new parameters.

Disableing Options

When SWICALL is run in File Driven Mode, all options are chosen by default. That is, SWICALL will attempt to create a .DAT, .TXT, and .UIS file for each SWIC, and attempt to print SWIC profile to the companion printer. However, you may disable any of these options. Note however that these options are not disabled on an individual basis. When you disable an option, you disable it for the entire program, until you run SWICALL again.

Option are disabled by entering certain key words on the command line. An example follows. In order to disable printing to the companion printer, type

   $ TESTP NOPRINT
other keywords are listed: You may enter more than one keyword. For example, to disable .DAT and .TXT files, you would type
   $ TESTP NOTEXT NOLOG
The order of the words does not matter. Also, if you choose NOPLOT, then NOPRINT is implied (there is nothing to print out). When using keywords, remember to leave whitespace between them.

External Driven Mode

In External Driven Mode, as in File Driven Mode, input comes from a text file. The text file is subject to the same restrictions as the test file used in File Driven mode. In fact, because both modes share the same input routines, the files are interchangeable. However, in External Driven Mode, the file is passed to SWICALL on the command line, using the following syntax:

   $ TESTP FILE:filename
You may use a file outside of your directory so long as you provide the complete VMS path name.

Also as in File Driven Mode, all option are chosen by default, but you may disable entire classes of options by using key words. For example:

   $ TESTP NOPLOT FILE:SWIC.NAMES NOTEXT
tells SWICALL to read the SWIC names from SWIC.NAMES, and not to create any UIS or TXT files. Recall that because NOPLOT was used, NOPRINT is implied. Note that the order does not matter, as long as the file name IMMEDIATELY follows the keyword FILE: --- no whitespace is permitted.

Once the carriage return is hit, SWICALL opens the input file, reads the SWIC names, and begins collecting and reformatting the SWIC data. SWICALL will write information and error messages to the screen as it executes.

A Final Note on Keywords

Keywords may also be used in Menu Driven Mode by typing:

   $ TESTP keyword
You probably noticed that this is the same syntax as using keywords in File Driven Mode. That is correct! SWICALL always checks the command line first, disabling any options indicated by keywords. Then SWICALL determines if it should run in External Driven Mode, or File/Menu Driven Mode. The Choice between File and Menu Driven Modes is made when you choose SETUP or FILE from the menubar.

Interpreting File Names and Types

File Names

Each file name has the following format nnnnn_yymmddhhmmss.xxx where:

This format insures a unique file name for each swic every time SWICALL is run, tells you at a glance when the data was acquired, and is a set format. An added bonus is that the files are automatically sorted chronologically. The time stamp is produced immediately before data aquisition begins, and remains the same for each session.

Thus, if you choose to look at N00WCS on February 14, at 9:15:23 pm, the timestamp will be 910214171523, and the file name will be N00WCS_910214171523. Cumbersome, but useful!

File Types

SWICALL can produces six types of file:

The .UIS, .DAT, and .TXT files have already been explained. Whenever a .UIS or .LJ250 file is produced, SWICALL also produces a .COM file. The COM file renames the initial .UIS or .LJ250 file to a time stamped file, and prints the .LJ250 file to the companion printer; a message will appear on your screen after each .COM file is executed. System output from executing the COM file is written to the .OUT file; look at this file if anything goes wrong with the .UIS or .LJ250 files. Now, if you have done your math correctly, you will see that as many as six files are produced per SWIC. That is a lot of files! However, as previously stated, the COM and OUT files do not contain data, so you may delete those. This leaves four types of files. The size of each type is listed below:

A Brief Note on UIS and LJ250 Files

In order to display a .UIS file, type:

   $ RENDER filename

In order to convert a .UIS file to an .LJ250 file, type:

   $ RENDER/DEVICE_TYPE=lj250 filename
This will create a file, named filename of default type .REN, printable on an LJ250 printer.

In order to print a file on an LJ250 printer, type:

   $ PRINT/QUEUE=queuename filename
SWICALL looks for the logical queuename UIS$PRINT_DESTINATION. The file should be of type .LJ250 or .REN.

Thus, if you wish to save 14 blocks per SWIC, you may instruct SWICALL to produce no .LJ250 files (use keyword NOPRINT), then RENDER and PRINT the .UIS files after you have checked that they contain interesting data.

Debugging

All program errors should first be reported to me, the program author, Tom Kobilarcik, RD/SOD Ops.

When new versions of EPICURE, UIS, or Vax C are released, SWICALL will most likely need to be recompiled. Furthermore, because of the changes, certain routines may behave unexpectedly. To help debug the program, three additional keywords (two ''debugging keywords'' and one ''data directive keyword'') and one preprocessor option are provided. They are:

The Debugging Keywords and Preprocessor Option

After every call to an EPICURE routine, the macro FAIL, which checks the returned status of the EPICURE call, follows. The evaluation of the macro depends on the compilation-time value of the macro RELEASE. The macro FAIL is defined as follows:

   void signal_failure( int );                   
   #if RELEASE
   #define FAIL(s) signal_failure(s)
   #else
   #define FAIL(s) if(s!=SS$_NORMAL)lib$signal(s)
   #endif
In order to define the macro FAIL, you must compile the program as follows:
   CC/DEFINE="RELEASE=1" SWICALL.C
Thus, when RELEASE is defined, FAIL is defined as the function signal_failure(). Otherwise, FAIL calls lib$signal when the returned status is not normal (i.e., not equal to SS$_NORMAL ). NOTE: SWICALL currently has RELEASE defined!

The function signal_failure() is defined as follows:

   void signal_failure( int sts )
   {
      int flag;

flag=control_flag&DEBUG_MASK;

switch( flag ) { case TEST: if( sts == SS$_NORMAL ) break; case TRACE: lib$signal(sts); default: break; } return; }

The function signal_failure() has been defined to respond in one of three ways, depending on which, if any, debugging keyword has been used. The three ways are:

  1. Do nothing (no debugging keyword chosen).
  2. Signal when an error occurs (TEST debugging keyword chosen).
  3. Signal returned status of every EPICURE call (TRACE debugging keyword chosen).
Because of this definition, and the fact that RELEASE is currently defined, extensive debugging may be done using the debugging keywords TEST or TRACE.

The Data Directive Keyword

On occasion, you may want to run SWICALL when there is no beam. To facilitate this, the data-directive keyword BOGUSDATA has been provided. When BOGUSDATA is included on the command line, SWICALL will read the SWIC wire data from a file named BOGUS_DATA.DAT instead of from the SWIC. In this case, SWIC status checking is omitted.

The file BOGUS_DATA.DAT must be present in the directory from which you run SWICALL. The file must contain 480 numbers separated by a carriage return. The numbers must range between zero and 255. A number out of this range will cause unpredictable behavior in the UIS sections of SWICALL.

Security, Privacy, Legal

rwest@fsus04.fnal.gov