"Logbook" Manual

 

 

 

Version 2.0

6 October 1999

 

 

 

 

S. M. Kaye

PPPL, Princeton University

Princeton N.J. 08543

  1. Introduction
    2.

    The electronic LOGBOOK is a widget-based IDL application program that allows any user to enter, edit, void, or view comments on individual plasma discharges (which are uniquely identified by the shot number) or on daily or XP activities (uniquely identified by Run Date and/or XP #, with a NULL shot #). The information for the LOGBOOK is stored in four tables in an MS-SQL database. The LOGBOOK allows any number of users to enter comments on a particular shot or experiment; each user is identified by his or her name, and a TOPIC (i.e., Session Leader, Physics Operator, MHD, Spectroscopy, etc.). The general philosophy of the LOGBOOK is that all comments that are entered are public, and that they can be accessed by any user. Private copies of the LOGBOOK can be kept by individuals; however, this requires the individual who desires a private copy to modify the application software to point to his/her private tables, and to maintain the tables oneself.

    The LOGBOOK application was originally developed for Alcator C-Mod by Josh Stillerman of MIT, and has been used in that form by DIII-D. The application was modified and adapted for use for NSTX by Stan Kaye. Major differences between the MIT and PPPL versions include a) separation of RUN DATE and SHOT for NSTX (C-Mod combines the two into a unique nine-digit shot #), b) inclusion of XP #, and c) inclusion of comments by the Session Leader and Physics Operator. These changes involved modifying parts of the code for defining selection criteria, developing queries and database updates, display and storage.

  2. Description of the LOGBOOK tables
    3.

    The LOGBOOK consists of information stored in four tables in an MS-SQL relational database. The four tables are named ENTRIES, TOPICS, RUNS, and SHOTS.

    The ENTRIES table is the primary table that contains the individual comments on the shots and XPs. The fields in the table are:

    ENTRIES

    USERNAME: user entering the comment (defined by the login)

    ENTERED: time and date that the comment was entered (system definition)

    VOIDED: time and date the comment was voided (automatic entry when comment voided)

    RUNDATE: date of shot or XP (user entry, or auto entry from table RUNS in format YYMMDD)

    SHOT: shot number (user entry or automatic update)

    XP: XP # (user entry)

    TOPIC: topic of comment (user entry)

    TEXT: comment (user entry)

    The TOPICS table contains the topics or comment descriptors. For instance, PHYS OPS and SESSION LEADER are topics (for comments entered by the Physics Operator or Session Leader). Other topics can include MHD, Spectroscopy, Analysis, Testing, etc. An arbitrary number of topics can be defined. If you would like one created, please contact me (S. Kaye), and I will enter it into the TOPICS table (this has to be done at the database administrator level). Once in the table, the topic is passed on for entry into the ENTRIES table by the LOGBOOK application software. The fields in the TOPICS table are:

    TOPICS

    USERNAME: database administrator who enters the topic name (determined at login time)

    ENTERED: date and time topic is entered into the table (system definition)

    TOPIC: name of topic (entered by the database administrator)

    BRIEF: brief description of the topic (entered by the database administrator)

    The RUNS table stores information about the experiment, and the application program to enter this information (described elsewhere) must be run prior to the start of each run day or XP. The application will be run by the COE or Physics Operator. It is important to run this application program, as the RUNDATE and XP information that is entered into RUNS is automatically picked up from the table by the LOGBOOK application program for entry into ENTRIES. If the program has not been run for that day, a message box telling you this will appear when you initiate LOGBOOK. Merely hit acknowledge and proceed; this information is primarily for the Physics Operator and Session Leader. Each entry in the RUNS table is uniquely identified by RUNDATE and XP #. The fields in the RUNS table are:

    RUNS

    USERNAME: user who enters the run information (COE, determined at login)

    ENTERED: date and time information entered (system definition)

    RUNDATE: date of experiment (user entry in YYMMDD format)

    XP: XP # (user entry)

    SLEADER: name of Session Leader (user entry)

    PHOP: name of Physics Operator (user entry)

    BRIEF: brief description of the XP (user entry)

    The final table that constitutes the LOGBOOK is SHOTS, and it contains information for use by the MDSPlus administrator (i.e., amount of data acquired, timing info, etc.) Updates of this table are automatic, and the information is generally not used by the physicists. Consequently, this table will not be described here.

  3. Initiating the LOGBOOK application
    4.

    The application program to enter the shot and XP comments into the ENTRIES table is IDL-based, and it must be run from within IDL on a VMS machine. To run the LOGBOOK application programs (hereafter referred to as LOGBOOK or LOGBOOK application), first initiate an X-windows session (on a MAC, PC, or Xterm display), and log onto a VMS machine. Once logged on, type

    > set display/create/node="your_Xdisplay_name"/transport=tcpip

    to define the location of the LOGBOOK display windows. Type

    > setup logbook

    to invoke the appropriate system definitions, and then

    > idl

    to start up an IDL session. Once in IDL, type

    idl> sql

    idl> syb_entry

    to initiate the LOGBOOK application. You are then ready to query, enter, edit, etc. comments from the ENTRIES table.

  4. Using the LOGBOOK application

The LOGBOOK application program can be used to view, enter, edit or void comments on individual shots or on XPs in the ENTRIES table. All information in this table can be accessed by anyone, but only the user who originally entered a comment can edit or void it. This section contains detailed instructions for using the LOGBOOK application, along with examples of the display windows.

When the LOGBOOK application is initiated (see Section III), a window entitled "Logbook Entries" will appear (with no entries). This window (shown in Fig. 1) has a menu line containing several main items: FILE, QUERY, ENTRY, and OPTIONS. On-line help is available using the HELP menu item to the right, and clicking on ABOUT, once the HELP window is displayed.

Fig. 1

The program will search for a selection and display defaults file, syb_entry_sk.dat, in your top-level directory. If it is found, it will use the constraints contained in that file. If it is not found, the program will create the file and fill it with some pre-defined constraints. You can change and save these constraints as described later. If syb_entry_sk.dat gets deleted, it will be recreated next time LOGBOOK is initiated. To obtain entries with this set of selection criteria, merely choose the QUERY menu item and select DO QUERY. This will retrieve the comments according to the constraints, and will display the comments in the main Logbook Entries window as shown in Fig. 2.

Fig. 2

Note that to the right of the QUERY menu item is a field that gives the number of records retrieved (NUM=x). To show the selection criteria used for this retrieval, select SHOW QUERY under QUERY (see ENTRY DISPLAY QUERY example in Fig. 3). The present default is to show all comments entered by the user, as defined by the system login (for this example, ‘KAYE’ is the user), and for all non-voided records. To proceed, click the ACKNOWLEDGE button in the window. How to change the default selection criteria will be explained later on.

Fig. 3

Returning to Fig. 2, the information shown for each entry consists of Rundate (YYMMDD format), Shot # (6 digits; NULL shot #s, which are used to enter general comments on XPs in ENTRIES, are denoted by ‘xxx’), XP #, user who entered comment, TOPIC of the comment, date and time the comment is entered, and, below this top line, the comment itself. Each entry is separated by a dashed line. During an experiment, the table will automatically be updated with a new comment, whenever a comment satisfying the selection criteria is entered into ENTRIES (by anyone). This will occur only if the AUTOMATIC UPDATE button is enabled in the lower right hand corner of the window.

 

In the following, each option of each menu item will be explained

IV.1) FILE

The options for the FILE menu item are (see Fig. 4):

PRINT: This presently does not work, but will be fixed.

Fig. 4

SAVE CURRENT SETTINGS:

Saves the current selection criteria (defined elsewhere) to the default file in syb_entry_sk.dat in your top level directory.

SAVE CURRENT SETTINGS AS…

Saves the current selection criteria (defined elsewhere) to a file whose location and name is prescribed by the user. A new window will appear allowing the user to prescribe this information.

RESTORE SETTINGS:

Restores selection criteria from syb_entry_sk.dat in your top level directory.

RESTORE SETTINGS FROM…

Restores selection criteria from file as chosen by the user. A new window will appear allowing selection of file by user.

EXIT:

Exits LOGBOOK application and returns user to IDL-level.

IV.2) QUERY

The QUERY menu item consists of four options that allow the user to make, show and customize queries, and to find text in the returned entries. Fig. 5 shows these options.

 

Fig. 5

DO QUERY:

Perform query based on present set of selection criteria (described earlier).

SHOW QUERY:

Show present set of selection criteria (described earlier, Fig. 3)

CUSTOM QUERY:

Allows user to set up a customized set of selection criteria for a query (see Fig. 6). Use of CUSTOM QUERY requires typing syntax consistent with SQL (Standardized Query Language), the default language for querying relational databases. Use of SQL-consistent syntax is not difficult. Examples of such syntax are:
    1. username=’kaye’ and xp=222: returns only those comments entered by ‘kaye’ for XP # 222
    2. rundate=990723 or (shot>1000 and shot<1100): returns comments made by anyone on any topic where either the date of the shot is 7/23/99, or the shot number is between 1000 and 1100

Fig. 6

The available fields and operators from which to construct selection criteria for the queries are shown in the CUSTOM QUERY window. Pressing OK on the bottom menu applies and selection criteria and performs the retrieval, the results of which appear in the Logbook Entries window (automatic updates are disabled for the CUSTOM QUERY). Note that the CUSTOM QUERY option does not change the set of default selection criteria that is read from the default file and stored in memory. Performing a DO QUERY under the QUERY menu item applies the default criteria, re-populates the Logbook Entries table, and re-enables the Automatic Updates.

FIND IN ENTRIES:

Allows user to search for a case-sensitive text string in any of the information displayed in the Logbook Entries window. For instance, the user can search for a particular shot #, XP #, etc. or can match text in the comment string. The pop-up window for this option is self-explanatory.

IV.3) ENTRY

The options under ENTRY allow the user to make, edit, and void entries (Fig. 7).

Fig. 7

MAKE ENTRY:

The window for making an entry is shown in Fig. 8, and it is entitled MAKE LOGBOOK ENTRY. In this window, the user specifies the Rundate and Shot #, etc., and this can be done in several ways. The Rundate, Shot, and XP can be entered directly into the boxes just under the menu line of this window. Alternatively, the Rundate and Shot can also be selected or updated by either clicking on the options given near the bottom of the window or on the options under the respective menu items for Rundate and Shot. The choices on either the top or bottom menu line are the same; you are merely given a choice of how to select them.

The choices are:

T: Track current – tracks and updates current Rundate or Shot #

C: Sets Rundate or Shot # to current value (gets current Rundate from RUNS table)

P: Sets value to previous Rundate or Shot #

N: Sets value to next Rundate or Shot #

I: Increments Rundate or Shot # from present value

D: Decrements Rundate or Shot # from present value

X: None – no entry (i.e., NULL value) for Rundate or Shot #. This can not be used for Rundate (there would be an error generated when an attempt is made to put the info into the database since there is a NO NULL constraint on Rundate), but can be used for Shot # to enter general comments about the experiment. These general comments could take the form of run plans or run summaries by the Physics Operator or Session Leader, or data summaries by the individual diagnosticians.

Once the user enters the comment in the main box in this window, the Make Entry option at the bottom of the page should be selected to actually enter the information in the database and automatically update the Logbook Entries window. Once the entry is made, the shot number will be incremented by 1 automatically in the display window. Note that unless this Make Logbook Entry window is Reset or Dismissed, it will stay active; Make Entry does not dismiss the window.

The Options menu item in Make Logbook Entry enables the user to set whether the comments in the main box are saved in the window after the record is entered or whether the comments are erased, in preparation for the next entry. The options for this in this menu item are: Erase Text After (entry), Keep Text After (entry), or Use Template. The default is Keep.

Fig. 8

EDIT ENTRY:

To edit an entry, first double-click on the entry you want to edit in the Logbook Entries window. The entry will become shaded. Then, select EDIT ENTRY from the ENTRY menu item. A window will appear in which you can edit the Rundate, Shot #, XP # or comment. You can only edit those records that have your login username. Click OK to enter the edited entry into the database and to update the Logbook Entries window. Click VOID to void the entry.

 

 

VOID ENTRY:

Voiding the entry can also be done by double-clicking on the entry of interest as above, and then selecting this menu item. A window requesting that you confirm the void will appear.

IV.4) OPTIONS

The OPTIONS menu (Fig. 9) item allows the user to set options for selecting records, displaying the information and printing the information.

Fig. 9

 

SELECTION OPTIONS:

This option allows the user to create a set of selection criteria for retrieval without having to create the CUSTOM QUERY which requires SQL-consistent syntax. When SELECTION OPTIONS is selected, a window entitled Specify Record Selection will appear (Fig. 10). The user can enter as many, or as few, selection criteria as desired. Options include Rundate for entries that are Not Voided only (default), Voided only or Both, Shot #, XP #, Shot Not Null only (for comments on individual shots), Null only (for general comments on the experiment), or Both (default), Username (default is "ME", where ME is the username as determined at login time, in this case "Kaye"), and any one of a number of Topics. More than one Topic can be selected. This can be done by clicking in the individual boxes, or selecting Select All on the bottom menu line; this selects all the Topics. Clear All on that menu line deselects all the Topics.

Fig. 10

Comparison operators (e.g., ‘>’, ‘<’, etc.) cannot be used with this method of creating selection criteria.

As examples, if you wanted all the comments for all the shots from a particular XP or Rundate, enter that XP or Rundate and leave the Shot box blank. If you want all comments for all shots, XPs, Rundates by a certain User or on a certain Topic, leave the Run Date, Shot and XP boxes blank and just select the Username (blank if all users’ comments desired) or Topics.

Clicking on OK at the bottom of the page performs the query based on these selection criteria, and updates the Logbook Entries window. Reset resets the Specify Record Selection window; Cancel dismisses the window, and Help brings up the Help window.

To save the set of selection criteria you created, go the FILE menu item in the Logbook Entries window and select SAVE CURRENT SETTINGS to save to the file in SYS$LOGIN and make these the set of default criteria, or SAVE CURRENT SETTINGS AS… to save to another file.

DISPLAY OPTIONS:

Allows user to display options for Logbook Entries (Fig. 11). User can sort by shot or time entered in ascending or descending order, and user can set automatic updates, scroll features and where the general comments (SHOT=NULL) are placed.

PRINT OPTIONS:

Allows user to set print queue (at present, the only choice is SYS$PRINT), page orientation and whether the output is saved in a file (and the file name if it is).

MAKE ENTRY OPTIONS:

Another way user can set display options in Make Logbook Entry window. This option brings up the window described in IV.3 under MAKE ENTRY, menu item OPTIONS. This directs whether the comments are kept or erased after the entry into the database is made.

 

 

Fig. 11