From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- doc/vmsprog.hlp | 572 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 572 insertions(+) create mode 100644 doc/vmsprog.hlp (limited to 'doc/vmsprog.hlp') diff --git a/doc/vmsprog.hlp b/doc/vmsprog.hlp new file mode 100644 index 00000000..bd8c7b2e --- /dev/null +++ b/doc/vmsprog.hlp @@ -0,0 +1,572 @@ +.help vms Nov85 "VMS/IRAF Programming Notes" +.ce +\fBVMS/IRAF Programming Notes\fR +.ce +Doug Tody +.ce +25 November 1985 +.sp 2 +.sh +Preface + + The purpose of this document is to serve as a guide to programming in the +VMS version of the IRAF environment. The discussion focuses on the +peculiarities of the NOAO VMS/IRAF environment rather than on the basics of +programming in IRAF; this is not an IRAF programming tutorial. The discussion +is intended for the practicing programmer using the NOAO/Tucson version of +VMS/IRAF, which includes the Eunice UNIX emulator and which is embedded in +a local network of four Vaxes and one Sun workstation. The discussion +describes the VMS version of IRAF as it currently exists at NOAO, with all +its bugs and defects, hence the document will rapidly become dated. + +.nh +Introduction + + The foreign task interface is now working well enough in the VMS version +of IRAF for me to recommend that IRAF software development and testing be +done from within the IRAF environment rather than in DCL. +All of the VMS facilities are easily and efficiently accessible, +plus one has the many advantages of the CL, e.g., +multiple commands on a command line, i/o redirection, ease of +spawning background jobs, logical directories, networking facilities etc. +The environment provides the basic tools we are used to on our UNIX based +systems (with help from Eunice), although the more subtle features of +UNIX are missing (e.g., OS escapes in VI or the debugger, job control, etc.). + +.nh +The NOAO VMS/IRAF Programming Environment +.nh 2 +The USER Package + + The USER package provides a way for the IRAF user to extend the IRAF +environment by adding IRAF or foreign tasks of their own choosing. +These extensions will normally be site dependent and will often vary from +user to user. In this section we describe the USER package for the IRAF +login on the NOAO VMS systems. The USER package is defined in the IRAF +login.cl file (usr1:[iraf.local]login.cl), which uses VMS logical names +defined in the IRAF login.com file (usr1:[iraf]login.com). + +The USER package is automatically loaded at login time since it is in the +login.cl file. The current contents of the package are summarized in the +menu below ("?u" to print when in the CL). The contents of this package +change frequently but it is likely that the present package already contains +the most frequently used utilities. Note that the standard \fBsoftools\fR +task are included for convenience. + + +.ks +.nf + adb grep mklib ps rlogin ruptime top who + chmod ls mkpkg purge rpp rwho touch wtar + diff mail mon pwd rsh sed update xc + finger make od rcp rtar su vdir xpp + generic man omake replace run telnet whereis +.fi +.ke + + +Many of the tasks shown here are simply foreign task definitions for the +Eunice/UNIX tools, which are used just as they are on a UNIX system. +Some of the others are less obvious and are described in the notes below. +.ls 4 +.ls 10 adb +Debug a VMS executable; short for "!run/debug". +For example, "adb x_x" will run the VMS debugger on file "x_x.e". +You should log in directly on the class 6 VAX rather than via \fBtelnet\fR, +else the screen will scroll rather than be randomly updated. +On VMS a process must be linked specially to be used with the debugger. +To do this, add the "-x" flag to the XC command line. +A task linked in this fashion CANNOT presently be run from the CL in the +normal fashion, so always use the "-o" flag to give the debug executable +a different name than the installed executable, e.g, "x_x.e". +.le +.ls run +The opposite of ADB. Runs a process linked with the debugger with DEBUG +turned off (i.e., a VMS run/nodebug). Will also run any normal (nondebug) +executable. +.le +.ls generic +The IRAF generic preprocessor. Usually run explicitly on VMS since the +Eunice MAKE has filename, etc. problems and cannot run many UNIX/IRAF +makefiles. Look in the UNIX makefile to get the command to feed to generic. +.le +.ls ls +The Eunice/UNIX directory lister. Used when you want to see multiple file +versions (these are invisible in an IRAF "dir" listing), +or when you want an "ls -lt" time sorted file listing. +The disadvantages of LS for normal use are that it +does not expand templates and does not unmap filenames. Note also that +recursive descent does not work in Eunice (at least not for me), hence commands +like "ls -R" will hang. +.le +.ls mail +Calls the VMS mail program. Whenever possible use UNIX mail instead to send +messages, unless you are sending mail to Nigel or some other diehard VMS type +who reads their VMS mail frequently. +.le +.ls mklib +The IRAF library maintenance utility. Also available in the \fBsoftools\fR +package. Essentially equivalent capability to the UNIX version. +A VMS manual page is appended. +.le +.ls mkpkg +Make package. Runs the "mkpkg.com" script in the current directory. +This is the VMS/IRAF equivalent of the "make" used on a UNIX system to +make or update a package. +.le +.ls mon +Monitor system. Equivalent to "!monitor system". Not as useful as the +UNIX task of the same name, but the output is prettier. +.le +.ls omake +Makes an object version of a file if one does not already exist; needed because +Make is not available on VMS. The only alternative in VMS is "xc -c file" +which is much slower since it always recompiles the named file. Note that +OMAKE does not check any include file dependencies. +.le +.ls ps +The Eunice version of PS. Contains a lot more information than the VMS +"show sys". The output from "ps -axu" is particularly useful. +PS is currently about the only thing on VMS which can tell you what command +another user is running. +.le +.ls purge +The VMS purge-old-versions task. Type "pu *.*" often when working in VMS. +The form "pu [...]*.*" will purge all old versions in the current directory +and below. +.le +.ls replace +Replace the named module in the named LIB$ library, e.g., + + cl> replace read.x sys + +would recompile "read.x" and replace the object module in the library +"lib$libsys.a", aka "iraflib:libsys.olb". This is primarily of interest +to systems programmers, since it works only on the system libraries in LIB$. +NOTE: this is a dangerous utility, since it is easy to replace (insert) +the module into the wrong library. +.le +.ls rtar +The IRAF read tarfile task. Used to unpack IRAF files from a tar tape, +or more commonly, from a tar format disk file pushed through the Ethernet. +A VMS manual page is appended. +.le +.ls telnet +Used to log in on a remote node. When logging onto a UNIX node from a VMS +node, frequent 's will be necessary when using utilities like PAGE +and VI to keep the terminal talking. +.le +.ls top +Display the processes currently using the most cpu cycles. Equivalent to +a "!monitor proc/topcpu". Similar to the UNIX "top" but takes no arguments +and returns less information about the resources consumed by the processes. +.le +.ls update +Update the named LIB$ system library by running MKLIB on the contents of +the current directory. This is like REPLACE except that it will hopefully +find and replace all recently modified modules in the current directory. +UPDATE is equivalent to the following sequence of VMS commands: + +.ks +.nf + $ copy iraflib:libXXX.olb [] + $ mklib libXXX.a + $ rename libXXX.olb iraflib +.fi +.ke + +Note the use of [] to signify the current directory, and the use of RENAME +to move a file to another directory. +.le +.ls vdir +The VMS directory lister. Used when one wants to ask VMS questions about +files, e.g., to query protections, get /full listings, etc. The advantage +of having this available as a foreign task (rather than just using an OS +escape) is that the output can be redirected into a file. For example, + + cl> vdir /full [...]*.exe > _exec + +will save in file "_exec" a /full format directory listing of all executables +in the current directory and below. +.le +.ls who +Equivalent to a "!show users". +.le +.ls wtar +The UNIX write tarfile utility. Used to save a directory tree in a portable +a UNIX "tar" format binary file. Use this with the "-o" (omit binaries) flag +to move sources back to UNIX. For example, + +.ks +.nf + cl> cd pkg + cl> wtar -of home:plarc [.plot] +.fi +.ke + +will make a tarfile "plarc" of the subdirectory "plot", assuming that HOME is +defined as a VMS logical directory name. Most variations on the command +shown here do not currently work. +A VMS manual page is appended. +.le +.ls xc +The IRAF XC portable compile/link utility. This task is also available in +the \fBsoftools\fR package. A VMS manual page is appended. +.le +.le + + +The USER package described here may be extended by copying the package +definition to your own login.cl file, then adding additional task definitions. + +.nh 2 +Foreign Tasks + + New foreign tasks may easily be defined at run time, for example when one +wants to capture the output of a VMS utility without having to edit a .com +file and submit a batch job (many VMS tasks do however have a /OUTPUT switch +which does much the same thing), or when one wants to run a foreign task +in the background. For example, + + +.ks +.nf + cl> task $vll = "$library/list/full" + cl> vll osfn("lib$libos.a") > _lib +.fi +.ke + + +defines a new task VLL which uses the VMS library to list the contents of a +library, then uses the new task to list the contents of the system library +LIBOS, saving the output in the file "_lib". Note the use of the string +valued intrinsic function OSFN to generate a VMS filename for the foreign +task. To discard a foreign task definition (or any task definition), exit the +package in which it was defined, or type "cl" before defining the task, +followed by "bye" at some later time to discard everything back to the "cl". + +A foreign task command is parsed by the CL just like any other IRAF command, +as is evident from the second example above. The arguments to a foreign +task may be arbitrary expressions; the CL reduces each such argument +expression to a constant value and passes this value to the host system as +a string. Note that VMS will convert all arguments to a single case unless +they are quoted. For example, + + cl> xc '"-cO"' file.x + +is the command to compile a file with optimization (the current XC default +is to not optimize). +Note that the first set of quotes are stripped off the by the CL, and the +second by DCL. + +.nh 2 +Filenames + + Avoid using the VMS meta-characters [ and $ in filenames when working +within the IRAF environment (except in calls to foreign tasks). To reference +a file in an arbitrary VMS directory you must first define the VMS directory +as an IRAF logical directory. Directories which are frequently referenced +should be defined in your login.cl file. + + +.ks +.nf + cl> set iis = sdk:[kpno.iis.prim] + cl> ed iis$foreign.f + cl> cd iis + cl> dir *.f + cl> back +.fi +.ke + + +The example above defines a new logical directory IIS and uses it to edit a +file therein, change to the directory, and so on. A reference such as the +following would fail because the system would try to do template expansion +on the [] delimited field. + + cl> page sdk:[kpno.iis.prim]foreign.for # won't work + +The following should work and will work in a future version of the system, +but does not work at present. + + cl> page sdk:\[kpno.iis.prim]foreign.for + +The mixture of IRAF, Eunice, and VMS tasks present in the USER package can be +confusing when it comes to filenames. +Most references to files in the current directory +are the same in all environments, but there are major differences +when pathnames are involved. To work effectively and without aggravation +you must know what type of task you are calling and supply the appropriate +type of filename. This is the price we pay for having direct access to +foreign tasks. + +.nh 2 +I/O Redirection and Background Execution + + I/O redirection will now work on VMS/IRAF for foreign tasks as well as +true IRAF tasks. The input or output of a foreign task may be redirected +on the command line; foreign tasks may be used in pipes. This is particularly +useful in combination with background execution, e.g.,: + + +.ks +.nf + cl> mkpkg >& spool & +or + cl> xc -c file1.x,file2.x,file3.f >& spool & +.fi +.ke + + +Background jobs currently run at a reduced priority on both UNIX and VMS. +At present any IRAF background jobs will be terminated when you log out of VMS. +Support for submission of IRAF background jobs to the VMS batch queues is +being actively worked on and will be available in the near future. + +.nh 2 +Editor Interface + + The NOAO VMS/IRAF editor interface currently supports the VI and EDT +editors (Emacs is also supported but we do not have the actual editor at NOAO). +One types "edit" or "ed" to invoke the editor; the choice of the actual +editor to be used is controlled by the \fBeditor\fR environment variable, +which may be set in your login file. + +The major limitation in the editor interface to VI is that template expansion +is not currently supported (the template is passed to the Eunice VI but it +is not expanded, since the UNIX shell normally does this for VI). +The ":!" OS escape mechanism does not currently work (for all but a few +commands) in the IRAF environment, although it does work in the Eunice cshell +environment. It is possible for the editor to have a different idea of the +current default directory than IRAF; if you suspect that this is the case, +type ":!pwd" to check and ":!cd /newdir" to fix it up. + +.nh 2 +Network Facilities + + Network access is currently available for the class 1, 2, and 5 Vaxes +from any other IRAF node, including the two VMS Vaxes and the Sun workstation. +All binary and text files and the class 2 (lyra) IIS may be accessed over +the network. Access to VAX/8600 hosted resources from the 750's will be +available shortly. For example, to copy a file from lyra to the current +directory when logged into IRAF on the 8600, any of the following equivalent +commands would work: + + +.ks +.nf + cl> copy lyra!/iraf/lib/fio.h fio.h + cl> copy 2!/iraf/lib/fio.h . + cl> copy 2!lib$fio.h . +.fi +.ke + + +Images may also be accessed over the network, provided there is a VAX at +both ends (this restriction will be removed when the DBIO based IMIO is +installed). + + +.ks +.nf + cl> set pix = 2!/tmp2/iraf/images/ + cl> implot pix$canon + cl> imcopy pix$canon canon2 +.fi +.ke + + +Copying an image from the local node to a remote node does not work at +present, even when IMDIR is defined to be on the remote node. I have not +yet had time to figure out why. + +Whenever a local process accesses a resource on a remote node the system will +spawn a "kernel server" process on the remote node. The kernel server +remains connected for the life of the local process, hence there is a delay +the first time a node is referenced (while the kernel server process is being +spawned), but all subsequent commands execute almost as fast as on the local +node. For example, there is a fixed delay of several seconds when an image +is first displayed from the 8600 on the lyra IIS, but thereafter image load +will be quite fast, so long as the image load process remains in the process +cache. + +The kernel server process must authenticate on the remote node with a login +and a password. By default the NOAO system currently uses the "ace" login for +this purpose; this is adequate for most purposes but, for example, printer +output will come out with an ACE jobname, and you will not have network write +access to your own files and directories. To have a fully functional network +interface you must add the file ".irafhosts" to your host system login +directory. This structure of this file is very simple and is best explained +by an example: + + +.ks +.nf + # Sample .irafhosts file. + + aquila lyra carina : login1 password1 + vela draco : login2 password2 + * : login3 password3 +.fi +.ke + + +Each line in the file associates a login name and password with a set of +hosts. Use the "real" host names in this file (e.g., "lyra"), not the +aliases (e.g., "2, class2"). The "*" line supplies a login and password +for any host machine and terminates scanning of the file, hence should be +given last. In the simplest case, i.e., where your login name and password +are the same on all hosts, the file may contain a single "*" type entry. +If the file contains your password it should of course be read protected. +For additional security the password may be given as "?" in which case you +will be asked for the actual password whenever a kernel server is spawned. + +.nh +VMS/IRAF Software Maintenance + + The IRAF group currently maintains IRAF simultaneously on a UNIX 11/750 +(node \fIlyra\fR) and on the VMS cluster (including both of the nodes +\fIdraco\fR and \fIvela\fR). Software is written and tested on the UNIX +11/750 and then installed and tested on the 8600, merging any bug fixes +from the VMS testing back into the UNIX version of the system. The UNIX 11/750 +is the primary software development system and contains the "master copy" +of IRAF. The 8600 is a production data processing machine and should not +be used for routine software development (algorithm development requiring the +speed of the 8600 is permitted, however). + +Each member of the IRAF group is responsible for installing and testing their +software on the 8600. Since the IRAF environment permits identical software +to be run on all IRAF hosts, the procedure for doing this is quite +straightforward. For example, assume we want to install a new version of +the PLOT package on the 8600. The following sequence of commands would +suffice to install an entire new version of the package. Incremental changes +are faster, but a full installation should be done occasionally to ensure +that the same software is running on both nodes. + + +.ks +.nf + (login on the 8600, get into the CL) + cl> telnet lyra + (log into lyra) + + % cd plot + % tar -cf ~/plarc . # make tar archive of plot + % rcp ~/plarc 6: # move tarfile to node 6=draco + % logout # go back to draco + + cl> cd pkg + cl> wtar -of usr0:[tody]plarc.bak [.plot] # make backup + cl> cd plot + cl> !show default # just in case... + cl> !del [...]*.*;* # delete nondir files + cl> !set prot [...]*.*;* # unprotect dir files + cl> !del [...]*.*;* # delete directory files + (repeat until all .dir files gone) + + cl> rtar -xof usr0:[tody]plarc # unpack new version + (fix up mkpkg.com files, if necessary) + cl> mkpkg >& spool & + (test everything once package is rebuilt) +.fi +.ke + + +At present the VMS version of each package is maintained by a DCL +"mkpkg.com" file. This is the only machine dependent software in an +IRAF package. To avoid having to recover the mkpkg.com files from the +WTAR savefile, you may wish to install the files in the UNIX version of +the package. The mkpkg.com files are quite simple since they just call +the portable IRAF utilities MKLIB and XC, but hopefully we will be able +replace the UNIX Makefiles and VMS mkpkg.com files by a single facility +in the future. + +As an example, the MKPKG.COM file for the plot package is shown below. +Note that the Makelib files, used by MKLIB to maintain the package libraries, +are portable since MKLIB is an (bootstrap) IRAF utility. + + +.ks +.nf + $! Make the PLOT package (VMS) + $! + $ mklib -i libpkg.a + $! + $ omake x_plot.x + $ omake x_ncar.x + $ xc x_plot.o libpkg.a -lncar -lgks -lxtools -o x_plot.e + $ xc x_ncar.o libpkg.a -lncar -lgks -lxtools -o x_ncar.e +.fi +.ke + + +Each time MKPKG is run new VMS versions of the executables will be added +to the PLOT directory. An occasional PURGE is necessary to remove the +old versions. + +.nh +Debugging on VMS + + Before an IRAF process can be debugged on VMS, the process must first +be linked using the "-x" flag to XC. For example the "x_plot.e" executable +shown above in the example of a MKPKG.COM file would be relinked for +debugging with the following command: + + cl> xc -x x_plot.o libpkg.a -lncar -lgks -lxtools -o x_x.e + +Note that the new executable is NOT called "x_plot.e", in case someone tries +to use the plot package while we are debugging it. To debug the newly +linked process we first check the ZZSETENV.DEF file to make sure that the +pathnames therein are up to date; they won't be if the package was recently +moved over from the UNIX system. + +Before debugging the executable make sure that you are logged in directly +on the VMS machine; do not login remotely via \fBtelnet\fR. Enter the +following command to begin debugging the process: + + cl> adb x_x + +For use in the IRAF environment the VMS debugger is run in screen mode, +language MACRO (assembler language debugging). Type GO to run the program +(the IRAF main prompt will appear); type EXIT to exit the debugger when +through debugging. This will sometimes leave the screen in a funny state +(a scrolling window less than the full screen may be defined). If this +happens, physically reset your terminal. The initial state of the debugger +is setup by the file "iraf$vms/init.dbg" which is referenced by the VMS logical +name DBG$INIT (which should be defined in your VMS login.com file). +You can change the initial state of the debugger by redefining DBG$INIT to +reference your own initialization file. + +Instruction in the actual VAX/DEBUG commands is beyond the scope of this +document; the best way to learn the debugger is to get an experienced IRAF +programmer to give a demo. The VMS document "Programming in VAX FORTRAN" +is the best documentation currently available for the VMS debugger. + +.nh +Comments on Performance + + Process spawning and inter-process communication appear to be slow in the +VMS operating system, compared to UNIX. When programming in an equivalent VMS +system (e.g., the VMS 11/750) all operations which involve process spawning +or inter-process communication will be noticeable slow compared to UNIX. +When programming on the VMS/8600 these operations seem to be comparable +in speed to an 11/750 running UNIX (actual process execution is of course +much faster on the 8600). Large files will compile faster on VMS than on +UNIX, but when compiling many small files the two systems are comparable. +Linking takes about the same amount of time on the UNIX 750 and on the 8600, +but the UNIX linker may actually be faster once the current cpu bound +inefficiencies in the UNIX linker are corrected (UNIX may win in the end +because of the UNIX buffer cache and the prelink facility provided by the +UNIX linker, but if we ever get sharable libraries working on VMS then it +may be faster). + +When it comes to actually executing a single scientific task, however, +VMS is in general slightly faster than UNIX running on equivalent hardware, +because the Fortran optimizer is slightly better, and VMS supports +asynchronous i/o. For these and other reasons (e.g., the availability of +UNIX on virtually all machines, the facilities provided by UNIX for software +development, etc.) it is best to do software development and other timesharing +activities on UNIX, reserving VMS for production use, i.e., data processing. +This is of course our current policy at NOAO. +.endhelp -- cgit