A brief guide to porting XAS software (XAS 1.1) DAWG-doc.xx/94 (to be assigned) (L.Chiappetti - IFCTR - Thu, 25 Aug 1994) These notes are issued together with the release 1.1 of the XAS libraries, and are directed to those who would like to implement XAS software on operating systems other than the ones officially supported (VMS and DECstation/Ultrix). Note that I am giving some unofficial support for SunOS Unix, and Daniele Dal Fiume is doing the same for HP-UX. These notes are essentially confined to porting to other flavours of Unix. Plans for porting from VAX VMS to AXP VMS are described in a separate note (DAWG-REP.9.0/93), however no work in this direction is planned in the near future. Porting to non-Unix and non-VMS systems is not envisaged at the moment, and will at least require a full rewrite of the entire VOS library. +---------------------------------------------------------------------+ | A) What has to be ported ? | +---------------------------------------------------------------------+ If the work is done correctly porting is not necessary for all main programs (the *.f files in $XASTOP/source) nor for all non-VOS "internal" libraries (i.e. the subdirectories of $XASTOP/libsource) with the following exceptions : There are some main programs (*.FOR) which are supplied as unofficial test versions for VMS and shall not be ported The importback and savenv programs are Unix-specific and may need to be ported. Some hints are given below. The "external" libraries are outside of my control. At the moment the external libraries are PGPLOT (consult documentation by ITESRE) and FITSIO. FITSIO 3.21 is supplied in source form with the release of XAS (for VMS, DEC and Sun). I am not aware at time of writing of the support status for HP-UX or other systems. If you want to embark in the enterprise of porting FITSIO you should better contact FITSIO's author, Bill Pence at GSFC. Since FITSIO is rapidly evolving at GSFC support within XAS has been frozen to 3.21. FITSIO is currently used in XAS only by 4-5 programs. +---------------------------------------------------------------------+ | B) Porting the bulk of the VOS library | +---------------------------------------------------------------------+ Now we come to the matter of XAS proper. Porting shall be necessary only for the VOS routines (the ones under $XASTOP/VOS). Most but not all of those routines were designed to be system-independent under Unix. Unless otherwise stated below, it is likely (although of course not guaranteed) that the Unix/VOS routines will work also under other Unixes. In any case you should never change the Fortran Z_ routines which are front-end interfaces to the C zc_ routines, unless you are really forced to (in such case I would appreciate to be informed, so that I could feed-back the changes if possible in order to mantain a common look for the Z_ routines). It is possible that the C routines as supplied work already. If your Unix is BSD-like (like DEC and SunOS) they should work as they are. If your Unix is System V-like (like HP-UX) they could work if they are compiled with the - DSYSV option. This has to do with the way the linker looks for a routine (a Fortran CALL PINCO will look for a C routine pinco_ in BSD, and pinco in Sys V), and is already accounted for by the #define statement at the beginning of each zc- routine. If they do not work, either they require minor massaging (in which case please let me know for the eventuality these could be fed back into a common version), or they require a different choice of the C system routine called (for an advice on a portable choice, ask Daniele Dal Fiume, who knows more on the matter). Do not convert (nor compile) the routines which are "not part of the official distribution" (these are mainly CPUCLK, ZC_DTIME, CHECKERR, Z_PRINT_FILE and Z_TAPE_OPEN, and the Z*SEEK routines). +---------------------------------------------------------------------+ | C) Routines which require specific changes | +---------------------------------------------------------------------+ 1) The BLKXRCOMMON routine is a BLOCK DATA routine which is used by the X_READ and X_PROMPT user interface routines. Here one has some possible changes : LUIN, LUOUT and LUERR must be assigned to the Fortran logical unit for the standard input, output and error (this is usually 5,6 and 0, but might be different on some systems, e.g. on HP stderr is 7) LUCOM is a reserved logical unit number used for command files; if your system supports logical units up to 32767 leave it as it is; if it supports a smaller range take if possible a value above 99 to avoid conflicts with the XAS programming rules. If not use 99 (as done in VMS) FORMAT is possibly OK as it is for all Unixes. If you get problems having the echo of a parameter on the same line as the prompt you may have to change this (compare the VMS solution) 2) deleted 3) Z_GET_COMMAND uses calls in the C-Fortran library to get the number of runstring arguments, and to get one argument at a time. You should change this routine to call the corresponding routines in your Fortran (again inspire to Ultrix/Sun version for BSD-like and to HP-UX for Sys-V-like). 4) The Z_OPEN routine is written entirely in Fortran (it cannot be otherwise since the files are opened for Fortran i/o) and its purpose is to conceal all system-specific details. It is possible that the Sun version is good enough for all Unixes (DEC/Ultrix is out of standard mainly for the fact it measures record lengths in 4*bytes). Another possible area of intervention are file protections. Compare the DEC and the Sun version. 5) The Z_OP_SYS routine is really a silly one. Pass back into SYSTEM a string identifying your operating system. If possible try to keep it within 3 characters (most other routines rely on that). I would like to be informed, to keep track of the assigned operating system codes. 6) The Z_SYSERRROR must translate all Fortran error codes (which you find in your system's Fortran manual) into standard codes. At the moment this is not done, so using the common version provided is a reasonable starting point. 7) The routine X_PROMPT (which is in the GENERAL library) uses the $ format to prevent a carriage return to be inserted after a prompt. This works on VMS, DEC and Sun. If this does not work in your case, move the routine to the VOS library and write a specialized version. 8) no changes should be necessary in X_READ, since the appropriate format for echos is set up in BLKXRCOMMON (see point 1). 9) Eventually have a look at the content of the include files in $XASTOP/include. If you need to change something there please inform me (I would like very much to keep these at all system independent) 10) for all the rest look at the extensive comments in the source code of all other routines. 11) The following changes are needed to make use of the "localize" program to convert XAS files from one system to another (please inform me so I can feed back the changes in the official version): 11.a) in $XASTOP/include you need to edit syscommon.inc and increment the parameter SYSCOMMON_NSYS by one 11.b) in the GENERAL library, in blksyscommon.f you have to add one element each to SYSCOMMON_NAMES, SYSCOMMON_INT, SYSCOMMON_FLO and SYSCOMMON_CHA. It is likely that you could just add your system name (PLEASE 3 characters!), and for the rest copy the values used for Sun.Refer to comments in the source listing. 11.c) if this is the case no further actions are in principle needed.However OPEN_OLD_XAS_FILE will need to be modified, because now, when finding two different operating systems, it will tell you need to convert, but later localize, finding the two operating systems are compatible, will tell you can use the file as it is. This will put you in a dead lock. Please inform me so I can do the change. 11.d) if your operating system uses non-standard representation for integer or floating point, you will need to change also the routine CONVERSION_NEEDED and to change extensively the code used by the LOCALIZE program. 12) Routine z_exit may also require changes. At the moment the Unix version has different behaviours (according to whether or not Fortran runtime library closes all logical units at exit or not). On Ultrix no action is necessary, however it is clean to close LUs 0-99. On HP it is necessary to close all units, but not stdin, stdout and stderr. On Sun only 64 file descriptors can be used, and closing a LU even if unopened uses one. To prevent core dump only opened LUs must be closed. Closing stdin, stdout and stderr is necessary for environment reasons but conflicts with i/o redirection. 13) A family of routines is required for "stream" i/o over pipes. There are two layers, a Fortran one (z_open_stream, z_close_stream, z_read_stream and z_write_stream) and a C one (zc_fopen, zc_fclose, zc_fread and zc_fwrite). If your system supports Fortran unformatted i/o over pipes without problems, you may try with the Ultrix approach (the z_*_stream routines use entirely Fortran, and the zc_f* routines are dummy no-op). You might need to change CHARACTER buffers to INTEGER ones, but in this case use the VMS version as example (take care of buffers which are not 4*n long with padding). If all these approaches fail, and/or you cannot keep synchronization between client and server (for bidirectional communication), use the HP/Sun version which uses C i/o. 14) Other routines to watch out are z_logintime and zc_stat (at least, we have found that the definition of the structure or files they use may be different on some systems, e.g. HP). +---------------------------------------------------------------------+ | D) Special programs | +---------------------------------------------------------------------+ 1) The savenv program is called by z_exit to save the environment in a file. It should not require changes, but in case have a look at the code and comments. 2) The purpose of the importback program is to read the file created by savenv, and to generate the appropriate "setenv" commands for the shell. The program uses a system dependent way to read the file (in Fortran), and tests which operating system is running under using a Z_OP_SYS call. Note that the same code is used by the routine Z_INITENV, so if you modify one, you should modify the other too. The two solutions contained there are one for Sun and the other for DEC. Here the fault is mainly on Sun : there is a deficiency in the way Sun does unformatted reads, and on the other hand DEC is limited for direct access to multiples of 4 bytes. Any solution towards an unique arrangement will be highly appreciated. +---------------------------------------------------------------------+ | E) Tools for compilation and linking | +---------------------------------------------------------------------+ Refer to xasbuild documentation for information on the tool used on Unix to generate Makefiles, and how it can be extended adding support to other systems and writing Proto makefiles. Refer to README files in the VMS distribution for the case of VMS Refer to XAS 1.0 Porting Guide (DAWG-MIS.10.92) for information about the Real Programmer Tool for Unix and VMS and the PATH facility for VMS.