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."
IDA is the shell in which you run SLD data analysis software.
IDA was developed by
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:
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 NTRACKSOr to define three variables,
Ida> VAR PT,ETOT,XTo assign a value to a variable, use
Ida> NTRACKS = 0In 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 = 28But the following will not work:
Ida> NTRACKS = NEWTWOYou 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 1A special kind of variable is a pointer to a Jazelle bank. You learned about this
POINTERexpression in the section of the workbook on manipulating Jazelle data.
Set up a pointer now using the
Ida> POINTER P_PHCHRG --> PHCHRGUsing 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
Ida> TYPE XThe TYPE command allows formatting options, such as
Ida> TYPE/F12.8 XWhen 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
Ida> DIRIn 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 SINHand the following functions of two arguments:
MIN MAX MOD ATAN2and the built in constants:
PI RADIAN = 180/PI DEGREE = PI/180These 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
Ida> DIR/SYSThose 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.
> Greater than < Less than >= Greater than or equal to <= Less than or equal to <> Not equal /= Not equal (alternate form) = EqualThe logical operators are
~ Not & And | OrThe 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> ENDDOYou should be able to get the same result many different ways, using
NEXTIFor 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> ENDIFIf 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.
PAUSEwill make the program pause until you type
CONTINUEwill make the program resume after a PAUSE
SPAWNwill suspend your IDA process and create a new VMS subprocess, like a new VMS session, in which you can issue DCL commands. When you
LOGOUTof this VMS subprocess, you will find yourself back where you were in IDA.
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
LOGOUTthat 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:10You should take care not to use
SPAWNtoo 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.
IDA allows you to encapsulate a group of IDA commands into a procedure.
To do so, use the
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> ENDDEFThe procecure
SHOWMEhas now been defined. To execute the procedure, type
CALLfollowed by its name or just type its name:
Ida> CALL SHOWME or Ida> SHOWMEGo 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
To demonstrate this, try the following:
Ida> DEF EVANAL Ida> PEEK IEVENTH.RUN Ida> PEEK IEVENTH.EVENT Ida> INDEX PHCHRG Ida> ENDDEFWhen 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> ENDDEFThe
DIRcommand 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
Ida> CLEAR SHOWMEVariables 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
DEF TYPEIT(MYINPUT) TYPE MYINPUT ENDDEFIf you then try to call this procedure, it will expect an argument. The following would pass the argument
4to the procedure which would then type
Go to your text editor and create a file in the directory where you are
running your IDA session. Call the file
Put the following lines into that file:
DEF SHOWKAL PEEK IEVENTH.RUN PEEK IEVENTH.EVENT INDEX PHKLUS ENDDEFNow, from your IDA session, include this code by typing:
Ida> @SHOWPROCIDA 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
ENDDEF so that the
file just reads:
PEEK IEVENTH.RUN PEEK IEVENTH.EVENT INDEX PHKLUSIf from IDA you now type
Ida> @SHOWPROCyou will see that the
INDEXrun 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)
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
Copy the following file to the directory from which you are running 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 WAITThen define your EVANAL to make the Z cut:
Ida> @ZCUTNow when you
GO 1an 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.
@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
*/ 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
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
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.
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> ENDDEFWhen you type in this
HISTcommand (or when IDA reads code like this in from a command file), IDA is in compilation mode. In this mode,
HISTis 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,
HISTis 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
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 IEVENTHThe peek would be executed immediately. It would not become part of the procedure.
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.