Workbook for SLD Offline Users - IDA Structure

IDA in Depth

Thanks for sticking with us this far.

Up to now, we have asked you to type many IDA commands without really teaching you the fundamentals of IDA. We did this because we thought you should see the power of the SLD software before you get bothered with details. We never explained IDA's syntax to you; we just told you what to type every step of the way. Now it is time to go back and learn some of the details of IDA.

This section of the workbook will cover the basic structure of IDA. First you will learn IDA's syntax for line structure, variables, program flow and IDA command files.

The next section of the workbook will give you some details on making histograms from IDA, reading and writing Jazelle data from IDA, and calling PREPMORT and C routines from IDA.

Then will come a section that describes routines you can call from IDA called "Processors" and "Command Processors."

Basic Structure

IDA is the shell in which you run SLD data analysis software. IDA was developed by Toby Burnett when he was working on the Mark III experiment at SLAC's SPEAR storage ring. Up to that time, there was no (or almost no) interactivity in the computing part of Physics data analysis. Users would set up a program to make a pre-determined output, then submit this program to run over some sample of events, then study the output (usually line printer hard copy) and then realize that they needed a slight change in the program and start over from scratch.

The idea behind IDA was to give the user some opportunity to modify their program while it was running. It was a new idea for most physicists and was very warmly received.

When Burnett joined the SLD collaboration, he brought IDA with him. The version he created for SLD was a major rewrite of the system, including many improvements that had occurred to him and tying in SLD's Jazelle data management system and SLD's error handling system. The resulting system allows for highly flexible examination and manipulation of complex structures of Physics data (PAW fans might want to know at this point that IDA allows a wider variety of data structures than PAW).

The basic syntax of IDAL, the IDA language, is a mix of ideas commonly seen in such languages as DEC DCL, IBM REXX and ANSI C.

You may see the names IDA and IDAL used interchangably around SLD (just like people mix up the names VMS, the DEC operating system, and DCL, the command language used in VMS). Even this manual will mix the two. But technically IDA is the shell program and IDAL is its command language.

A few of the most basic features of IDAL are as follows:

there is no end of line character used
if a line ends with a comma or a dash, the next line is treated as a continuation of that line (be sure to precede the comma or dash by at least one space)
any text after an exclamation point is treated as a comment
case generally does not matter. Commands are converted to upper case before they are analyzed, except for text enclosed in double quotes.

Variables

All variables in IDAL are Real*4. This limitation has made life a little difficult for SLD. This workbook will show you some tricks to handle these type conversion when it is necessary. (A different version of IDA, called IDA3, has since been developed by Toby Burnett and gets around this restriction. But this version has not yet been adapted for SLD). All variables in SLD's IDA language are REAL*4.

Start an IDA session now if you don't already have one open. As you continue reading this section of the workbook, run the examples shown in your IDA session so that you become familiar with how correct responses look from IDA.

Variables are defined by the VAR command. For example, to define a variable to be called NCHARG,

   Ida>  VAR NTRACKS

Or to define three variables,

   Ida>  VAR PT,ETOT,X

To assign a value to a variable, use =

   Ida>  NTRACKS = 0

In the above statement, you have the option of including a decimal point after the zero or not. In any case, IDA will assign the value to the variable as a REAL*4.

If you try to assign a value to a variable for which you have not yet issued a VAR command, IDA will still accept this (it issues the VAR command for you). This automatic assumption is only done for you if your variable is on the left side of the equals sign. If you try to use a variable on the right side of the equals sign before you have defined it, IDA will refuse.

Thus, the following will work:

   Ida>  NEWVAR = 28

But the following will not work:

   Ida>  NTRACKS = NEWTWO

You can use any of the standard arithmatic operators and parentheses, + - * / **

   Ida>  A = (B + C**2) * (D - E/F)

Open some data now so that we have some Jazelle data to work with.

   Ida>  OPENTAPE READ REC94_MDST STAGE WAIT
   Ida>  GO 1

A special kind of variable is a pointer to a Jazelle bank. You learned about this POINTER expression in the section of the workbook on manipulating Jazelle data.

Set up a pointer now using the POINTER command:

   Ida>  POINTER P_PHCHRG --> PHCHRG

Using this pointer, you can then fill a variable from a quantity in a Jazelle bank.

   Ida>  X = P_PHCHRG%(HLXPAR(4))

As mentioned above, IDA variables are always REAL*4. If the quantity from the Jazelle bank is not REAL*4, IDA will automatically perform the necessary type conversion.

To write out the current value of a variable, use TYPE

   Ida>  TYPE X

The TYPE command allows formatting options, such as

   Ida>  TYPE/F12.8 X

When you first issue VAR to define a variable, you can specify a default format for all typing out of that variable. But remember that these options only affect how the variable is typed out, internally, IDA still carries the variable around as a REAL*4. Issue the IDA commands HELP VAR and HELP TYPE for details.

To see what variables are currently defined, use the DIR command

   Ida>  DIR

In addition to the simple arithmatic operators listed above, IDA has a more detailed math library. It contains the following functions of one argument:

   ABS   SQRT  INT   FLOAT
   ACOS  ASIN  ATAN  COS   SIN  TAN
   EXP   ALOG  COSH  TANH  SINH

and the following functions of two arguments:

   MIN   MAX   MOD   ATAN2

and the built in constants:

   PI
   RADIAN = 180/PI
   DEGREE = PI/180

These functions can be used in expressions such as:

   Ida>  RIMP=SQRT((X**2)+(Y**2))

Still more functions, including a large set of functions from CERNLIB (the software library of the SLAC's European sister laboratory, CERN), can be found by issuing another form of the DIR command:

   Ida>  DIR/SYS

Those items in the resulting list that have Type starting with X are functions of some number of variables, where the number of variables is given after the X.

Program Flow

In all of the following command definitions, only the part of the command shown in UPPER case is required. The part shown in lower case is optional.

a loop is delimited by the lines DO and ENDdo.
a while block is delimited by the lines WHILE and ENDwhile
a special kind of loop, which loops over all Jazelle banks of a given family is delimited by the lines BANKLOOP and ENDbankl
an IF block is delimited by the lines IF, ELSEIF, ELSE and ENDif
to force an exit from a repeat block, EXITif
to force the next iteration of a repeat block, NEXTif

The relational operators are

   >   Greater than
   <   Less than
   >=  Greater than or equal to
   <=  Less than or equal to
   <>  Not equal
   /=  Not equal (alternate form)
   =   Equal

The logical operators are

   ~   Not
   &   And
   |   Or

The following silly piece of code would type out the numbers one through four:

   Ida>  DO X = 0 TO 10
   Ida>     TYPE X
   Ida>     EXITIF X > 3.5
   Ida>  ENDDO

You should be able to get the same result many different ways, using WHILE or NEXTIF or other options from above. Use IDA's HELP system for details.

Be careful not to rely on the value of the loop index once you have left the loop. In the above example, the X in the loop is not the same X you would see if you tried to type it out after the loop. Try it. If you type out X, you will see whatever value X had before you ran the loop, not the 4. that you might expect. There are really two different variables X, one inside the loop and another outside the loop.

The following piece of code writes out whether X is greater than ten or not:

   Ida>  IF X > 10
   Ida>     TYPE "X is Greater than 10"
   Ida>  ELSE
   Ida>     TYPE "X is not Greater than 10"
   Ida>  ENDIF

If the above gave you the error message IDA error executing IF (4) it means you need to do a VAR X to define X to be a variable.

There are a few other commands you will want to know related to program flow.

PAUSE will make the program pause until you type CONTINUE
CONTINUE will make the program resume after a PAUSE
SPAWN will suspend your IDA process and create a new VMS subprocess, like a new VMS session, in which you can issue DCL commands. When you LOGOUT of this VMS subprocess, you will find yourself back where you were in IDA.

This last command, SPAWN, can be very useful. If you just want to execute a single DCL command, you can include this command right after the SPAWN. IDA will spawn a subprocess, execute that one command, then immediately LOGOUT that subprocess and return to IDA.

For example, the following IDA command uses SPAWN to make the program wait ten seconds before continuing:

   Ida>  SPAWN WAIT 00:00:10

You should take care not to use SPAWN too many times in a single job. Each subprocess takes time and consumes other system resources.

In the above examples, the loops and the IF statements ran as soon as you finished defining them. If instead what you want is to define the loop now and run it later, you need to put the loop inside of a "Procedure." Read on.

Procedures

IDA allows you to encapsulate a group of IDA commands into a procedure. To do so, use the DEF and ENDdef commands.

Here is an example of a procedure which uses the Jazelle commands PEEK and INDEX to give us some information about an event:

   Ida>  DEF SHOWME
   Ida>     PEEK IEVENTH.RUN
   Ida>     PEEK IEVENTH.EVENT
   Ida>     INDEX PHCHRG
   Ida>  ENDDEF

The procecure SHOWME has now been defined. To execute the procedure, type CALL followed by its name or just type its name:

   Ida>  CALL SHOWME
      or
   Ida>  SHOWME

Go to the next event and try SHOWME again. Then try a third event.

When you made your first DO loops and IF statements, the reason they ran as soon as you finished typing them was that IDA treated them as "Implicit Procedures." That is, IDA converted them into procedures as soon as you finished typing them and then ran and deleted those procedures.

You can use almost any name for an IDAL procedure. But if you use the special name, EVANAL, for your procedure, then you get the extra feature that the procedure is automatically executed every time you go to a new event. The name EVANAL stands for EVent ANALysis procedure. You already defined EVANALs many times in previous sections of this workbook. You can now see that DEF EVANAL is just a special case of the more general purpose DEF command.

To demonstrate this, try the following:

   Ida>  DEF EVANAL
   Ida>     PEEK IEVENTH.RUN
   Ida>     PEEK IEVENTH.EVENT
   Ida>     INDEX PHCHRG
   Ida>  ENDDEF

When you type GO, the procedure will run without having to be explicitly called for each event.

Procedures can call other procedures. For example, you could define your EVANAL procedure to call your SHOWME procedure:

   Ida>  DEF EVANAL
   Ida>     SHOWME
   Ida>  ENDDEF

The DIR command that you already learned to see what variables are have been defined will all show you what procedures have been defined.

If you do another DEF with the same procedure name as you have used before, your new definition will replace the old one.

To remove a procedure definition entirely, use the CLEAR command:

   Ida>  CLEAR SHOWME

Variables which you define within a procedure are only available within that procedure. They are "local" variables. Variables which you define outside of any procedure are available within all procedures. They are "global" variables. An exception is the loop indices we mentioned earlier, which are never available outside the loop.

A procedure can accept arguments. For example, the following simple procedure accepts an argument called MYINPUT.

   DEF TYPEIT(MYINPUT)   
      TYPE MYINPUT
   ENDDEF

If you then try to call this procedure, it will expect an argument. The following would pass the argument 4 to the procedure which would then type 4..

   TYPEIT 4

The @ Sign: Writing and Calling Command Files

IDA procedures can be stored as files on disk and then included into the IDA session by using the @ command.

Go to your text editor and create a file in the directory where you are running your IDA session. Call the file SHOWPROC.IDA. Put the following lines into that file:

   DEF SHOWKAL   
      PEEK IEVENTH.RUN
      PEEK IEVENTH.EVENT
      INDEX PHKLUS
   ENDDEF

Now, from your IDA session, include this code by typing:

   Ida>  @SHOWPROC

IDA copies the code from your command file into your current session. Note that it doesn't run the procedure SHOWKAL, it just defines it. Thereafter, when you type SHOWKAL, IDA runs the procedure.

Now modify your SHOWPROD.IDA file to remove the first and last statements, the DEF and ENDDEF so that the file just reads:

      PEEK IEVENTH.RUN
      PEEK IEVENTH.EVENT
      INDEX PHKLUS

If from IDA you now type

   Ida>  @SHOWPROC

you will see that the PEEK and INDEX run immediately. This may seem an obvious point to you, but with more complicated examples users sometimes get confused about whether @ defines a procedure or runs it. The answer is that @ has the same effect as if you had typed in the code that is in the procedure file.

You can call command files from other directories by adding the directory specification after the @ sign. For example, the following would start up a demonstration version of the event display (the display will take some time to load, so don't do this now unless you feel like you need a break)

   Ida>  @PRODDISPLAY:DSPDEMO

Recursive calling is allowed, that is, a command file can call itself. But this is rarely good programming practice and can lead to lots of trouble.

Now that you are familiar with the @ command, we can finally stop making you type in long strings of IDA code. As soon as IDA code gets complicated, most users choose to write their code in a text editor and call it with the @ command.

Copy the following file to the directory from which you are running IDA:

SLACVX::DISK$FAC0:[SLDWWW.WORKBOOK]ZCUT.IDA

This command file sets up some variables and then defines an EVANAL that can be used to select high quality Z events.

If you don't still have your data file open, open it now:

   Ida>  OPENTAPE READ REC94_MDST STAGE WAIT

Then define your EVANAL to make the Z cut:

   Ida>  @ZCUT

Now when you GO 1 an event will be put through the Z cut procedure. NTRACKS will be the number of good tracks in the current event and CNT will keep a running count of how many good events are seen.

Two Different Command Languages: IDAL and REXX

The command files you call with the @ sign from your IDA jobs can be written in IDAL as described above, or they can be written in a different command language called "REXX."

REXX is a language that was originally developed for use on IBM VM systems and has since been adapted to Unix, to Amigas and, just for SLD, to DEC VMS.

You should write command files in IDAL if they are to do simple tasks. They will run faster than if they were written in REXX.

You should write command files in REXX if they need to do more complex tasks, especially tasks involving complicated manipulation of strings or involving passing numbers to routines that do not expect REAL variables (we will discuss this near the end of this section of the workbook).

IDA determines whether a command file is IDAL or REXX by checking the first line of the file. If the first line looks like a REXX comment line, IDA assumes the file is REXX. A comment line in REXX is enclosed by the characters /* and */ as in the following example:

   /* This is an example of a REXX comment line */

We won't go into much more detail about REXX here. Just be aware that some of the command files you may encounter may be REXX. Get in the habit of checking the first line of any command file to see if it is IDAL or REXX. REXX command files can call almost all IDA commands, but they use a different syntax from IDAL (lines end in semicolons, IF statements require THEN statements, and so on). Copy the syntax from examples that you find or find a REXX manual, such as the "uni-REXX Reference Manual" published by The Workstation Group, LTD, or an online guide such as IBM's REXX Information Gopher or the ARexxGuide by Robin Evans.

One serious limitation to note if you do start writing command files in REXX: a REXX command file cannot use the @ command. That is, while you can call a REXX file from an IDAL file, you can not call an IDAL file from a REXX file.

If you are writing in IDAL but have a single line that you prefer to express in REXX, just start that line with the word REXX. Try HELP REXX from the IDA prompt for details.

One other interesting note: IDA itself is written in REXX.

Compilation Mode and Execution Mode

IDA has two different modes: "compilation mode" and "execution mode." When IDA is in "compilation mode," it is recording your statements rather than immediately executing them. IDA is in this compilation mode when you are in the middle of typing a DEF/ENDDEF structure or when you are in the middle of typing one of the other structures that IDA takes as an implicit procedure (an IF structure or any kind of loop).

As IDA records these statements, it "compiles" them, which is to say it converts them into its own internal language. It also does some error checking, seeing if the lines you typed make any sense (so that IDA can provide an error message to help you right away).

When you finish typing this structure (when you type the ENDDEF, ENDIF or any of the other kinds of ends), IDA switches back to "execution mode." If the procedure just ended was an implicit one (an IF or a loop), IDA executes the procedure as soon as it switches back to execution mode.

Most of the time, you don't have to think about what mode IDA is in. But if IDA ever behaves in a way that seems confusing, it is useful to think about whether it is in compilation mode or execution mode.

The HIST command provides a good example of the difference between IDA's two modes. You used this command in the First Day section of this workbook to make a histogram.

Here is the code you typed:

   Ida>  DEF EVANAL

   Ida>    PEEK IEVENTH.EVENT

   Ida>    BANKLOOP PHCHRG
   Ida>      HIST PHCHRG%(HLXPAR(2)) FROM 0 TO 10 ID 1 TITLE "HLXPAR(2)"
   Ida>    ENDLOOP

   Ida>  ENDDEF

When you type in this HIST command (or when IDA reads code like this in from a command file), IDA is in compilation mode. In this mode, HIST is taken as a command to define a new histogram that will have the given range, ID and Title. Later, when the EVANAL is run, IDA is in execution mode. In this mode, HIST is taken as a command to accumulate data into the histogram.

The compilation mode action on this HIST command occurs only once. The execution mode action occurs many times (once for every PHCHRG bank for every event).

If IDA is in compilation mode but there is a command you want to execute immediately, you can start the command with the word IMMediate. The command is executed immediately. It does not become part of the procedure.

Uses of the IMMediate command are not very common. But you might use it if you were in the middle of defining a complicated procedure and you quickly wanted to check the names of some quantities. For example, if you had forgotten what the quantity names were in the IEVENTH bank, you could type

   Ida>  IMM PEEK IEVENTH

The peek would be executed immediately. It would not become part of the procedure.

Conclusions

You have now reviewed the detailed structure of IDA. You may not be able to write elaborate IDA code blindfolded, but you will at least recognize the various IDA structures when you encounter them in other people's code.

The next section of the workbook talks about three special sets of commands that you can call from IDA. It teaches you details on making histograms from IDA, reading and writing Jazelle data from IDA, and calling PREPMORT and C routines from IDA.

Back to Workbook Front Page

Joseph Perl
10 February 1995