12.3 AIPS language

AIPS contains a basic set of symbols and keywords which are needed to construct a computer language, as well as the symbols needed by the application code. A list of the basic symbols is given in the help file called POPSYM, reproduced below:

Type:  Symbols used in the POPS interpretive language  
 
    VERB      USE        COMMENTS  
 
                   ----Arithmetic expressions  
 
     +       A + B       Add the expression A to B  
     -       A - B       Subtract the expression B from A  
     *       A * B       Multiply the expression A with B  
     /       A / B       Divide the expression A by B  
     **      A ** B      Calculate A to the power B  
     ( )     (A+B)*C     Grouping expressions as desired  
     =       A = B       Store the value of B into A  
     ,       A = 3,5,4   Separator of elements in an array  
     ~       A(i) ~ 1,2,3  Store values in A(i),A(i+1)...  
                         (change only as many as on RHS)  
     :       TO          Equivalent to the verb TO  
     ;                   Separator between AIPS statements  
 
                   ----Logical expressions  
 
     >       A > B       A greater than B  
     <       A < B       A less than B  
     =       A = B       A equal B (numeric or string)  
     >=      A >= B      A equal to or greater than B  
     <=      A <= B      A equal to or less than B  
     <>      A <> B      A not equal to B (numeric or string)  
     !       A ! B       A or B  
     &       A & B       A and B  
     ^       ^ A         not A  
 
                   ----String expressions  
 
  !!       A !! B        string = string A followed by string B  
  SUBSTR   SUBSTR(A,i,j) string = chars i through j of string A  
  LENGTH   LENGTH(A)     position last non-blank in A  
  CHAR     CHAR(A)       convert number A to string  
  VALUE    VALUE(A)      convert string A to number  
 
 
                   ----Looping constructions  
 
  (FOR-TO-BY-END)        FOR I=1 TO 7 BY 2  
                         <any valid set of AIPS syntax>  
                         END  
 
  (WHILE-END)            WHILE <any logical expression>  
                         <any valid set of AIPS syntax>  
                         END  
 
  (IF-THEN-ELSE-END)     IF <any logical expression>  
                         THEN <any valid set of AIPS syntax>  
                         ELSE <any valid set of AIPS syntax>  
                         END  
 
                   ----Built-in functions  
 
  ACOS          Arc-cosine - output in degrees  
  ASIN          Arc-sine - output in degrees  
  ATAN          Arc-tangent (one argument) - output in degrees  
  ATAN2         Arc-tangent (two arguments) - output in degrees  
  COS           Cosine (degrees)  
  SIN           Sine (degrees)  
  TAN           Tangent (degrees)  
  EXP           Exponential  
  LN            Log base e  
  LOG           Log base 10  
  SQRT          Square-root  
  MAX           Maximum i.e. X = MAX (A, B)  
  MIN           Minimum i.e. X = MIN (A, B)  
  MODULUS       Root-square sum of two arguments  
  MOD(A,B)      A - (A/B) * B  i.e. remainder of A/B  
  CEIL(A)       Lowest integer >= A  
  FLOOR(A)      Highest integer <= A  
 
                   ----Procedure building verbs  
 
  PROC      PV  Begin building a procedure  
  PROCEDUR  PV  Begin building a procedure  
  LIST      pV  List a procedure  
  EDIT      PV  Edit a procedure  
  ENDEDIT   PV  End editing a procedure  
  ERASE     PV  Delete line(s) of a procedure  
  MODIFY    PV  Modify a line in a procedure  
  RETURN    V   Last statement in a procedure  
  FINISH    PV  End procedure building  
 
                   ----Variable declarations  
 
  SCALAR    pV  Declare scalars  
  ARRAY     pV  Declare arrays  
  STRING    pV  Declare strings  
 
                   ----Input/Output functions  
 
  PRINT     V   Print the following keyword value(s)  
  TYPE      V   Print the following keyword value(s)  
  READ      V   Read value(s) from terminal after # prompt  
 
                   ----Other information  
 
  CORE      pV  Amount of core left in POPS  
  COMPRESS  PV  Compress the core area, recovering lost space  
                and acquiring any new vocabulary  
  CLRTEMP   V   Clear the temp data array  
  DEBUG     pV  Debug: turns on compiler debug information  
  DUMP      V   Dump K array on terminal screen  
  SCRATCH   PV  Remove procedures in POPS  
  $         PV  Makes rest of input line a comment

12.3.1 Using POPS outside of procedures

POPS variables are either numeric or character valued and may be multi-dimensional arrays. Once created, all variables are available everywhere, i.e., they are global. You may manipulate these variables on the command line using most of the symbols listed above. In fact, you have been doing this while setting the adverbs for all the tasks and verbs described in preceding chapters. The more advanced user may wish to use some of the language features in order to simplify repetitive data processing. Here are some simple examples of uses of the AIPS language:

> TYPE (2 + 5 * 6)  C R

32 is written on the terminal.

> TYPE ’X =’, ATAN (1.0)  C R

X = 45 is written on the terminal.

> TYPE ’MAPNAME ’, INNAME, INCLASS, INSEQ  C R

MAPNAME  3C138  IMAGE  1 is written on the terminal.

The simplest loop capability in AIPS uses the pseudo-verbs FOR, TO, and BY for repetitive operations. Such loops are primarily intended for use in “procedures” (see 12.3.2). If a FOR loop can be typed fully on one input line, it will also work outside the procedure mode. The following example shows how to delete a series of images with the same name and class and with consecutive sequence numbers 1 through 10:

> INNA ’TEST’ ; INCL ’IMAGE’  C R

to set (fixed) name parts.

> INDI 1  C R

to set (fixed) disk number.

> FOR INSEQ = 1 TO 10 ; ZAP ; END  C R

to delete the files.

FOR loops must be terminated with an END. The following example shows how to delete every other file in a catalog with 20 entries:

> FOR INSEQ = 1 TO 20 BY 2 ; GETN(I) ; ZAP ; END  C R

More extensive examples are shown in the sections below on procedures.

In some cases, you may wish to manipulate character strings to give your files meaningful names — particularly if your RUN file or procedure operates repetitively on many similar files. The verbs for character manipulation are listed above. As an example,

> OUTNAME = ’CLEAN’ !! CHAR(BLC(3))  C R

to name each output file after the input image plane.

Note that trailing blanks are ignored. If you wanted a space after CLEAN before the plane number, use

> OUTNAME = ’CLEAN’  C R

to set the basic form.

> SUBSTR (OUTNAME , 7 , 12) = CHAR (BLC(3))  C R

to alter only the last six characters of OUTNAME.

12.3.2 Procedures

Procedure building is a way to combine keywords in AIPS in any convenient way to obtain useful constructs. For complicated sequences, it is easier to prepare and debug procedures in RUN files (12.2.1) than to prepare them in interactive AIPS. A procedure is given a name, with or without arguments, and then can be treated as an AIPS verb. As an example, consider a procedure to load an image on the TV, set the cursor, and fit for the maximum intensity. You could type the following on your terminal:

> PROC MFIT (I)  C R

to define procedure MFIT with one argument I. (I and J are two dummy adverbs which are already defined in AIPS.)

: GETNAME(I)  C R

(Notice the prompt symbol : . This means that we are in the procedure-building mode.)

: TVLOD ; IMXY ; MAXFIT  C R

to load the image, produce and read the cursor, and fit the maximum near the cursor position when a TV button is pressed

: RETURN  C R

to designate a return point in the procedure — normally not required at the end of a procedure unless a value is to be left on the stack, i.e., a function.

: FINISH  C R

to designate the end of the procedure-building mode and to get back into the normal (prompt >) mode.

> 

Notice the prompt symbol, you are back to interactive input mode.

When you type such a procedure into AIPS, the code is compiled as you type. Most syntax errors are spotted immediately and will unceremoniously dump you out of procedure mode. However, all lines written before the detected error are kept and the procedure editor can be used to continue.

The AIPS procedure editing capabilities are quite primitive. If you want to build procedures longer than about five lines, we therefore recommend using permanent storage files in the “RUN” area, as discussed in 12.2.1 above.

To list the procedure MFIT, type:

> LIST MFIT  C R

This will produce the following:

1PROC MFIT(I)
2 GETNAME(I)
3 TVLOD ; IMXY ; MAXFIT
4 RETURN
5 FINISH

The procedure is identical to what you typed, with line numbers added.

Procedures are edited line by line. To edit line 2 in the above procedure, type:

> EDIT MFIT 2  C R

to enter Procedure editing mode.

; GETNAME(I) ; TVLOD  C R

(Notice prompt symbol ; for procedure-editing mode.) This change replaces the old line 2 adding a TVLOD.

; IMXY ; MAXFIT  C R

to add a line between the changed line 2 and old line 3.

; GETNAME(I+1)  C R

to add yet another line after 2.

; ENDEDIT  C R

to terminate procedure editing.

> LIST MFIT  C R

Listing the modified procedure will give:

1PROC MFIT(I)
2 GETNAME(I) ; TVLOD
3 IMXY ; MAXFIT
4 GETNAME(I+1)
5 TVLOD ; IMXY; MAXFIT
6 RETURN
7 FINISH

To delete lines n through m from a procedure, type:

> ERASE xxxxxxxx n : m  C R

where xxxxxxxx is the name of the procedure.

To insert one or more lines between lines 3 and 4 of a procedure, type:

> EDIT xxxxxxxx 3.5  C R

; (Type additional lines as needed.)

; ENDEDIT  C R

Notice that the lines are renumbered after any EDIT or ERASE. Use LIST to determine the new line numbers.

The pseudo-verb MODIFY lets you modify characters within a line of a procedure to correct the line or change its meaning. The grammar is:

> MODIFY proc-name line-number

where proc-name is the name of the procedure and line-number is the line number in the procedure as shown by LIST.

MODIFY begins by showing the existing line with a ? as a prefix. Then it prompts for input with a ? To keep the character of the original line immediately above the cursor, type a blank (space-bar). To delete that character, type a $ (dollar-sign). To replace that character, type the new character (to get a new blank character, type an @ sign). Insertions complicate things. To insert text prior to the character immediately above the cursor, type a \ followed by the desired text followed by another \. You may continue to MODIFY the remainder of the line, but you must remember that the current character position in the old line is to the left of the current cursor position by the number of inserted characters (including the 2 \’s). MODIFY will display the resulting line of code after you hit a carriage return ( C R) and does not change the line number. Example:

> MODIFY  ED  2 |CR  
?TYPE ’THIS IS EDS PROC’  
?              MY@\NEW\     @FOR@EXAMPLE’ |CR  
TYPE ’THIS IS MY NEW PROC FOR EXAMPLE’  
> MODIFY  ED  2 |CR  
?TYPE ’THIS IS MY NEW PROC FOR EXAMPLE’  
?                 $$$$    \EDURE,\ |CR  
TYPE ’THIS IS MY PROCEDURE, FOR EXAMPLE’

More information about procedure building and editing can be found by typing:

> HELP PROCEDUR  C R

Procedure creation and editing uses up the limited memory of the POPS processor. When the memory is gone, the message BLEW CORE! will appear and you can do no more procedure writing without starting over (i.e.RESTORE 0  C R). CORE  C R will tell you how much memory is left. If the memory remaining appears small, try COMPRESS to recover the lost memory (in 15JAN96 and later releases). COMPRESS might even work after a BLEW CORE! if you are lucky.

The procedure MFIT can be executed by:

> MFIT(n)  C R

where n is the slot number of the appropriate image.

(It is assumed that the correct disk unit number has already been set.) This procedure can also be part of another procedure or put in a loop. For example:

> FOR I= 1 TO 10 BY 2; MFIT(I) ; END  C R

will load the TV and fit the maximum for the first ten images on the appropriate disk.

All the syntax available in AIPS is available for use inside procedures except for certain pseudo-verbs. The “prohibited” pseudo-verbs include SAVE, GET, STORE, RESTORE, PROCEDURE, EDIT, ENDEDIT, MODIFY, LIST, CORE, SCRATCH and COMPRESS. Others do not make much sense in procedures, including MSGKILL, DEBUG, and ABORTASK. Other pseudo-verbs are, however, particularly useful in procedures. These include TGET, TPUT, and GO.

Several verbs are extremely useful in procedures. To set the image name adverbs to those visible on the TV, use TVNAME. When GETN accesses an empty slot, an error condition is raised and the procedure dies. To handle this error condition in your procedure, use EGETN n instead and test the adverb ERROR which will be “true” if the slot is empty. CHKNAME may be used similarly to check on the existence of files with computed names. Some tasks require image-data dependent inputs. To help handle this in general procedures, the verb GETHEAD allows all header parameters to be fetched into adverbs. Type EXPLAIN GETHEAD  C R for details. Verbs GETTHEAD and TABGET perform similar functions for data in table extension files. The verb GETPOPSN fetches the current POPS number for use in procedures, for example, to allow the same procedure to run concurrently in multiple AIPS sessions. The verb DELAY will cause AIPS to pause for a specified period of time — MFIT above would benefit by pausing to allow the user to see his images. There are numerous arithmetic functions, useful looping constructions, and powerful methods of building arithmetic, logical, and string expressions in POPS. See 12.3 above for a list of these. CLRTEMP may be used in procedures which do a lot of looping. It clears the temporary space used to hold sub-strings and other temporary constants. A procedure that does much string manipulation is likely to overflow this area after a number of iterations. The message BLEW TEMP C! usually accompanies the overflow.

Once a procedure is written and edited, it can be stored in a SAVE file for later use. Procedures are lost when another GET file is obtained. Procedures can be stored more permanently in RUN files which are described in 12.2.1 above. To list the names of all procedures currently in your AIPS environment, type:

> HELP PROCS  C R

This will list internal AIPS procedures as well as your own.

Several procedures have been built into AIPS. In particular, some procedures are defined in the system RUN file VLAPROCS to aid routine calibration of VLA data. Currently, these are VLACALIB, VLACLCAL and VLARESET. Similarly, VLBA reductions are aided by the procedures in the file named VLBAUTIL. They may be useful templates for your own procedures. If you are unfamiliar with the use of AIPS procedures, looking at these system-supplied ones will help you to understand, and see the power of, this feature of AIPS.

12.3.3 Writing your own programs with POPS

You may want to add your own programs to AIPS. It is not a trivial matter to generate an AIPS-standard FORTRAN program (see HELP NEWTASK  C R, the Going AIPS manuals, and 12.6 below). Simple but powerful programs may however be built as procedures that use existing verbs and tasks.

Consider a the following example. (This example is presented as if it were typed into an interactive AIPS. In practice, you will probably prefer to prepare such a complicated procedure as a RUN file.) We wish to determine the average value and rms scatter at any pixel location in a set of n images. We shall demand that the n images all have the same INNAME and INCLASS with sequence numbers between 1 and n. The RENAME verb can be used to name the images appropriately. We could call this procedure:

AVGRMS (PIXXY, N, AVG, RMS)

where

PIXXY is the pixel location in the images,
N is the number of images,
AVG is the average value at the pixel location, and
RMS is the rms value at the pixel location.

The array adverb PIXXY is a standard AIPS adverb, but the variables N, AVG, and RMS are unknown to AIPS. These must be defined before we can write the procedure AVGRMS. This is done by a short dummy procedure which we will call DAVGRMS:

> PROC DAVGRMS  C R

to define dummy procedure.

: SCALAR N, AVG, RMS  C R

to define scalar adverbs.

: FINISH  C R

to exit from dummy procedure.

Now begin the procedure AVGRMS:

> PROC AVGRMS (PIXXY, N, AVG, RMS)  C R

to enter procedure building mode.

: SCALAR SUM, SUM2  C R

to define more variables.

: ARRAY VAL(20)  C R

to define an array.

: RMS = 0 ; SUM = 0 ; SUM2 = 0  C R

to zero some variables.

: FOR INSEQ =1 TO N  C R

to begin summing loop.

: QIMVAL  C R

to get pixel value at PIXXY in image INNAMEINCLASSINSEQ.

: VAL(INSEQ) = PIXVAL  C R

to save pixel value (placed in PIXVAL by IMVAL) in our array.

: SUM = SUM + PIXVAL  C R

to sum for averaging.

: SUM2 = SUM2 + PIXVAL * PIXVAL  C R

to sum for rms.

: END  C R

to mark end of FOR loop.

: AVG = SUM / N  C R

to get average value.

: IF N > 1.5 THEN  C R

to check if N > 1.

: RMS = SQRT((SUM2 - N*AVG*AVG) / (N * (N-1)))  C R

to calculate rms if N > 1.

: ELSE ; TYPE ’N TOO SMALL’, N  C R

to warn the user.

: END  C R

to mark end of IF clause.

: TYPE ’AVG=’,AVG,’RMS=’,RMS,’AT PIXEL’,PIXXY  C R

: TYPE # ’,’ VAL ’,’ ERROR  C R

to print a heading.

: FOR INSEQ = 1 TO N  C R

to begin another loop.

: SUM = AVG - VAL(INSEQ)  C R

to get residual.

: TYPE INSEQ, VAL(INSEQ), SUM  C R

to print data and residual.

: END  C R

to mark end of FOR loop.

: FINISH  C R

to return to regular AIPS mode.

> 

The above procedure could be run as follows. First fill in the adverbs INNAME, INCLASS and PIXXY with the desired values. Then type:

> AVGRMS (PIXXY, n, AVG, RMS)  C R

where n is the number of images to average. The average and rms will be calculated and written on the terminal and in the message file. This procedure could be used by another procedure. Suppose we wanted to determine the average and rms of the pixels within a rectangular area. If we set BLC and TRC in the usual way to define the rectangular boundary, then the procedure:

> PROC AVGARRAY (BLC, TRC)  C R

to define new proc.

: FOR I = BLC(1) TO TRC(1)  C R

to loop over x-coordinate

: FOR J = BLC(2) TO TRC(2)  C R

to loop over y-coordinate.

: PIXXY = I , J  C R

to set pixel coordinates for AVGRMS.

: AVGRMS (PIXXY, N, AVG, RMS)  C R

: END ; END  C R

to end y loop, then x loop.

: FINISH  C R

to end the proc., RETURN not needed.

> 

will calculate the average value and rms at this array of pixel locations. Please note that this is just an example. The verb IMSTAT performs this function much more efficiently.

12.3.3.1 Special facilities for use in procedures

When a task or verb encounters an error condition, it sets an error flag which normally causes POPS to terminate the line or procedure it was executing. You can avoid the termination due to task failure by setting DOWAIT FALSE and then doing a WAIT on the task. This does not let your procedure know that an error in the task occurred, but it does let you ignore any possible error. Certain verbs have a second version which sets the ERROR adverb, rather than the automatic termination flag. These include CHKNAME which checks for the existence of an AIPS file with specified name parameters, EGETHEAD which returns a keyword value from a header or ERROR if the keyword is not present, EGETNAME which returns ERROR if the catalog slot is empty, COPIXEL which returns ERROR if the coordinate is not in the image, and SYSTEM which returns ERROR if the function fails. Several fitting verbs, IMVAL, MAXFIT, QIMVAL, TVFLUX, and TVMAXFIT, return ERROR if the fit fails. Your procedure can test ERROR after these verbs and take appropriate action.

Numerous verbs return adverb values which may be used in your procedures. These include COPIXEL, COWINDOW, EGETHEAD, EGETNAME, EPOCONV, GAMMASET, the various GETNAMEs, GETHEAD, GETTHEAD, GREAD, IN2TV, IMDIST, IMPOS, IMSTAT, IMVAL, IMMXY, MAXFIT, QIMVAL, REBOX, SET1DG, SETSLICE, SETXWIN, TABGET, TK1SET, TKBOX, TKNBOXS, TKSET, TKVAL, TKWIN, TV1SET, TVBOX, TVCOLORS, TVDIST, TVFLUX, TVMAXFIT, TVNAME, TVPOS, TVSET, TVSTAT, and TVWINDOW. GETHEAD and the table functions GETTHEAD and TABGET are particularly useful in procedures. The verb NAMEGET, new in 31DEC12, will convert the INNAME set of adverbs to the values that would be used by a task.

The RUN file VLBAUTIL provides interesting procedures such as MAXTAB which returns the maximum table number of a specified table type. Other procedures in that RUN file include ones that return antenna number corresponding to a specific name and ones that test whether a data set appears to be new and appears to contain only VLBA antennas. MAXTAB has been made obsolete by the verbs GETVERS and QGETVERS, new in 31DEC12, which perform the same function, returning adverb MAXVERS either with or without messages.

Several tasks now return adverb values. These values can then be used for later computation. These tasks include CUBIT, GAL, FINDR, IMEAN, IMFIT, JMFIT, RLDIF, and SETFC. The first two of these return image fit parameters, the next two return uv and image statistics, the next two return the results of Gaussian fitting, RLDIF returns the phase difference between RL and LR polarizations for polarization calibration, and SETFC returns imaging parameters including number of facets, cell size, and image size.

There is also a verb named SYSTEM which allows the AIPS user to fork a command to the host operating system from within AIPS including from within procedures. This may be used to delete unwanted text or FITS files, to run ftp to fetch data files from the web, to run another copy of AIPS, or any of a very large number of other commands. The verb FILEZAP will allow you to delete nonAIPS files without use of the SYSTEM verb.