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:

12.3.1 Using  outside of procedures

 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:

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:

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

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,

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

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 . A procedure is given a name, with or without arguments, and then can be treated as an  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:

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  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:

This will produce the following:

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:

Listing the modified procedure will give:

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

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

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 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:

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

Procedure creation and editing uses up the limited memory of the  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:

(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:

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, TUGET, 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  number for use in procedures, for example, to allow the same procedure to run concurrently in multiple  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 . 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:

This will list internal  procedures as well as your own.

Several procedures have been built into . 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  procedures, looking at these system-supplied ones will help you to understand, and see the power of, this feature of .

12.3.3 Writing your own programs with

You may want to add your own programs to . It is not a trivial matter to generate an -standard FORTRAN program (see HELP NEWTASK  C R, the Going  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:

where

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:

Now begin the procedure AVGRMS:

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

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:

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  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  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, 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 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 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  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 non files without use of the SYSTEM verb.