1. Introduction

Caution
 The beta2 pre-release of the FS does not make on older Linux distributions such as FSL8. The beta1 pre-release does make on FSL8. This is fixed for FSL8 in beta3, which also has a workaround for even older distributions.

This update is intended as a test version for all stations using the FS. This includes both stations using the main (non-VGOS) branch (latest version 9.13.2) and the VGOS branch (latest versions 9.12.10-9.12.13). Installing the new version as update for these cases is fairly simple but has several steps, see the Upgrading from an FS9 version section below.

The most significant changes in 10.0.0 are:

  1. One unified version for all FS users.

    Both non-VGOS and VGOS operations are supported by the new version. Previous installations of the main (non-VGOS) branch will need to have some new local control files added.

    The most significant change for users is that previous main branch users will find that in the new FS input is case sensitive, as it was already in the VGOS branch.

  2. Support for use on both 32- and 64-bit systems.

    The new version should run on 32-bit systems that currently support the FS (we expect to support as far back as FSL8, but currently FSL9 is the limit), as well as on 64-bit systems. The update notice includes instructions for transitioning to a 64-bit system, which may require some relatively simple changes to station software. See the 64-bit conversion document for more details.

    A new FS Linux distribution, FSL10 (based on Debian Stretch), is now available for 64-bit (and 32-bit) use. We recommend using this distribution if you would like to move to using a 64-bit OS or need a 32-bit OS that is still under support (the base Debian distribution, Wheezy, used for FSL9, and those for older FSLx versions, is no longer under support). This also may be an alternative for users with distributions (such as FSL7) that are too old to support the current FS. Installation instructions for FSL10 can be found at https://nvi-inc.github.io/fsl10.

  3. Version control with git.

    The FS source is now managed using git and github is used for distribution. The source code is now under the GPL3 license.

    The details of the model used for FS releases under git are described in the Release Model document.

    This change increases the importance of not modifying the /usr2/fs directory tree since such changes will make it more difficult to simply pull updates to install bug fixes and new features.

  4. The FS display server is now recommended for normal use.

    This change is new as of the beta2 release.

Please also see the section Changes from FS9 below for details of the changes compared to the latest FS9 versions.

Essential contributions were made by Dave Horsley (UTAS, Australia and NVI/GSFC) and Tetsuro Kondo (NICT, Japan and SHAO, China). Kondo-san pioneered 64-bit support in the FS with his 64-bit implementations for the Sejong and Ishioka stations. Dave built on his work in developing a version that would support 32- and 64-bit systems.

Dave also single-handedly imported the entire existent history of FS source code into git. This includes over 130 FS9 versions (under Linux), 17 FS8 versions (under VENIX), and two older versions (under HP RTE-1000/A) going back to version 5.5 in 1988. Having the source code in git greatly simplified the task of merging the main and VGOS branches. Dave also did the most critical work on that and provided excellent guidance on using git. Having the historical code in git is a great resource for understanding the evolution of the code.

As always, we are deeply indebted to Jonathan Quick (HartRAO, South Africa) for his many significant contributions that go far beyond what is explicitly mentioned below. In this particular case, his contributions include testing and insights for adapting the code for 64-bit use, patiently solving various problems, developing FSL10, making many helpful suggestions for changes, testing, and providing feedback.

We also think Beppe Maccaferri (Medicina) for being a diligent beta tester, reporting bugs, helping test several fixes, and making helpful suggestions for changes.

We would also like thank Eskil Varenius (Onsala) bug reports and feedback, particularly on DBBC3 related issues.

2. Other useful documents

This section provides links to some other useful documents.

2.1. Other related upgrade documents

Upgrading from beta2 to beta3.

Upgrading from beta1 to beta2.

Upgrading from FS9 to 10.0.0-beta1 (text document): https://raw.githubusercontent.com/nvi-inc/fs/259e203330fff145dba5ea6b2f48c8bcd23b4333/misc/fs10.0.0up.txt.

2.2. Miscellaneous

Known bugs document with the known bugs list from FS9.

Installation reference document with other useful install information is available. It includes eight sub-sections:

  1. Upgrading from FS versions before the previous stable

  2. Example standard procedure libraries

  3. Copy-and-paste installation tips

  4. Making a back-up before installing

  5. Disk space requirements

  6. Set operations file permissions

  7. Fix .prc file define lines

  8. Setting geometry values in .Xresources

If you haven’t upgraded or installed the FS before, you may want to review the appendix. It is strongly recommended that you back-up your operational system before upgrading.

3. Upgrading from an FS9 version

Caution
 The beta2 pre-release of the FS does not make on older Linux distributions such as FSL8. The beta1 pre-release does make on FSL8. This is fixed for FSL8 in beta3, which also has a workaround for even older distributions.

This section covers upgrading from FS9, which was always 32-bit only, to 10.0.0-beta2. It is assumed you are upgrading on a 32-bit system. There are two possible paths for upgrading:

  1. Upgrading from a main branch version. The main branch versions are numbered 9.13.x and 9.11.x or older. Specifically, versions 9.12.x are not part of the main branch. If you are upgrading from a main branch version, it is assumed that upgrade is from 9.13.2, the previous stable release. If you have a main branch version older than version 9.13.2 you should upgrade to 9.13.2 first, please refer to the Upgrading from FS versions before the previous stable section in the Installation reference document for more information.

  2. Upgrading from a VGOS branch version. The VGOS branch versions are numbered 9.12.x. The instructions provided in this section are for installing as an upgrade to versions 9.12.10-9.12.13, the latest VGOS branch releases. As far as we know, no other VGOS versions are in use. If you have a different version, please email Ed for more information.

The upgrade instructions for the update from the old main branch and the old VGOS branch differ only in the step Update control files.

Tip

It is also possible to upgrade to a new installation on a 64-bit system. Doing so will allow you to upgrade to 10.0.0 and 64-bit without disturbing your operational 32-bit system. However, the upgrade may be more involved because it may require additional changes and testing for your station software. The instructions for combining the FS and 64-bit upgrade are:

  1. Follow the steps in the 64-bit Conversion document down to the Make local software step. Instead of following that step, return to the next item in this TIP.

    This step will result in a base FS10 installation on a 64-bit system with your local software, control files, and procedure files from your FS9 32-bit system. That is an inconsistent configuration, which will not work properly. The local software will have been updated for 64-bit, but not tested. Your local software and other local files need to be updated for 10.0.0, which is covered in the next step.

  2. To update your local software and other local files for 10.0.0, follow the instructions in this document, beginning with the Case sensitive strings in antenna= commands sub-step and continue with remaining steps.

    When you get to the Test the FS sub-step, you may need to debug your station software.

To upgrade from FS9 to FS10 on a 32-bit system, please follow the steps below.

3.1. Back-up your operational system

Having a back-up to return to will allow you to continue operations in case something goes wrong with the installation. For more details, please see the Making a back-up before installing section in the Installation reference document.

Note
 If you are using FSL10 with a RAID, that sub-section points you to the improved backup and test procedure that is available with that distribution.
Note
 That section also includes a description of how to preserve your operational files and switch back and forth between an operational and a test set-up by changing symbolic links.

3.2. Login as root

Login as root.

3.3. Download the FS

Place a copy of the FS git repository in the /usr2 directory on your computer. For example, you might do the following:

cd /usr2
git clone https://github.com/nvi-inc/fs.git fs-git

or alternatively, if you are using FSL8 or other old Linux distribution, or otherwise need to use ssh instead:

cd /usr2
git clone git@github.com:nvi-inc/fs fs-git
Tip
 Using ssh requires you to have a gitub account and for you to add an ssh public key from your machine’s root account to your github account. For more information, go to https://github.com/join and https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account.

3.4. Checkout the release

Checkout the beta2 release from the local repository:

cd fs-git
git checkout -q 10.0.0-beta2

3.5. Set the /usr2/fs link

Set the link for the new FS version:

cd /usr2/fs-git
make install

Answer y to confirm installation.

Caution
 This step will change your /usr2/fs symbolic link to point to /usr2/fs-git. To switch back to your old version, you will need to change the link manually.

The make install command may create and possibly rename some existing directories if the FS was never installed on this system before. However, since you should only be following this path if you are upgrading an FS9 installation, there should not be any problem.

3.6. Fix file permissions

Having the wrong ownership and/or permissions on the operational files (procedure libraries, control files, schedules, and logs) can cause errors during FS operations. For a full discussion, please refer to the Set operations file permissions section of the Installation reference document. For stations where all the operational files are expected to owned by user oper in group rtx, with permissions ug+rw,o+r,o-w, the following command will enforce this (note that the execute/search bits are not changed):

/usr2/fs/misc/fix_perm

Answer y to the prompt if you wish to proceed. It is recommended for most stations.

3.7. Login as prog

Important
 Logout as root, and login as prog.

3.8. Set FORTRAN compiler

Starting with version 10.0.0, the standard FORTRAN compiler for use with the FS is f95 (gfortran). We recommend that you use it. On the 32-bit systems you can still use fort77, but you should only use it if you either don’t have f95 or if you have FORTRAN station code that is too difficult to convert to f95, see sub-step Conversion of FORTRAN code for more details.

To select f95 as your compiler, you will need to set the FC variable to this value. If your shell is tcsh you can use:

setenv FC f95

If your shell is bash, you can use:

export FC=f95
Warning
 For beta testing on a 32-bit system, you may not want to make this change permanent since it is incompatible with pre-10.0.0 versions.

To make this change permanent, you should add the appropriate command to the appropriate rc file depending on your login shell: ~prog/.login for tcsh or probably ~prog/.profile for bash.

3.9. Make the FS

Caution
 The beta2 pre-release of the FS does not make on older Linux distributions such as FSL8. The beta1 pre-release does make on FSL8. This is fixed for FSL8 in beta3, which also has a workaround for even older distributions. 
cd /usr2/fs
make >& /dev/null

and then

make -s

to confirm that everything compiled correctly (no news is good news).

3.10. Update station programs

This step is for modifying your station programs in /usr2/st. There are two possible issues:

3.10.1. Conversion of FORTRAN code

If you don’t have any FORTRAN station code, you can skip this sub-step. If you do have some, please email Ed so he is aware.

Basically you have two options (also see step Set FORTRAN compiler):

  1. Change to using f95 for both the FS and your station FORTRAN programs. It is recommended that you follow this approach for 32-bit systems and it is necessary when moving to a 64-bit system.

    You will need to adapt your Makefiles to use the same compiler options as the FS, which can be found in /usr2/fs/include.mk. As a first cut, it may work to add the following two lines to your Makefiles for FORTRAN programs:

    FFLAGS  += -ff2c -I../../fs/include -fno-range-check -finit-local-zero -fno-automatic -fbackslash
FLIBS   += -lgfortran -lm

  2. Continue to use fort77 for both the FS and your station programs. You should follow this approach only if you are on a 32-bit system and it is too difficult to convert to f95.

3.10.2. Case sensitive strings in antenna= commands

In FS9 versions, the strings used in antenna=…​ commands were always converted to uppercase before being sent to antcn. An part of the FS input being case sensitive that no longer happens. If your antenna, or your side of the antenna interface, requires that the strings passed by the antenna=…​ command are uppercase, you have two options:

  1. Convert your code. For simple backward compatibility, change you antcn program to always convert the antenna=…​ strings to upper case. Alternatively, make your code case insensitive.

  2. Convert the strings in your antenna=…​ commands wherever they occur: SNAP procedures, SNAP schedules, external programs, or scripts, to upper case. Field system input is now case sensitive.

The former choice is probably the easier, but in some cases the second may be better. If you have questions about which to use and how to do it, please email Ed.

3.11. Make local software

If /usr2/st/Makefile is set-up in the standard way, you can do this with:

cd /usr2/st
make rmdoto rmexe all
Note
 At this point, you are only trying to verify the code will make successfully. You may still need to debug it in the step Test the FS below.

3.12. Reboot

Important
 Reboot the computer. This is necessary to allocate FS, and possibly station, shared memory for the new version.

3.13. Login as oper

The remaining steps assume you are logged in as oper.

3.14. Update control files

This step is for updates to the local control files. There are five sub-steps:

  1. Update stcmd.ctl

  2. Copy control files

  3. Update equip.ctl

  4. Review control files

  5. Update rdbemsg.ctl

Differences for updating from different previous versions are noted. Please read all cases in each sub-step carefully to make sure you find all the cases for your old version; sometimes an old version is included in more than one case in a sub-step.

3.14.1. Update stcmd.ctl

  1. Old version 9.13.2:

    The non-comments lines need another digit added to the subroutine number. This sub-step is only need for updates from 9.13.2. You can fix your file with the commands:

    cd /usr2/control
/usr2/fs/misc/cmdctlfix6 stcmd.ctl

    You may also want to expand the (typically) second comment line to correspond to the new format by adding a U after character 18 to read as:

    *COMMAND     SEG SUBPA BO

3.14.2. Copy control files

You will need to execute the following commands to copy new files that are needed (copy-and-paste is your friend). There are three cases depending on what your old version was:

  1. Old versions 9.12.10 and 9.12.11:

    cd /usr2/control
cp /usr2/fs/st.default/control/clpgm.ctl .
cp /usr2/fs/st.default/control/rdbemsg.ctl .

  2. Old versions 9.12.12 and 9.12.13:

    cd /usr2/control
cp /usr2/fs/st.default/control/rdbemsg.ctl .

  3. Old version 9.13.2:

    cd /usr2/control
cp /usr2/fs/st.default/control/dbba2.ctl .
cp /usr2/fs/st.default/control/mk6c?.ctl .
cp /usr2/fs/st.default/control/monit6.ctl .
cp /usr2/fs/st.default/control/rdbc?.ctl .
cp /usr2/fs/st.default/control/rdbe.ctl .
cp /usr2/fs/st.default/control/rdbemsg.ctl .

3.14.3. Update equip.ctl

It is necessary to add lines for the FiLa10G input select and the DBBC3 configuration. There are three cases, please check which applies for you. In any event, you should compare your equip.ctl to the example as described when you get to sub-step Review control files below, to make sure there are no duplicated lines or other problems caused by the commands in this current sub-step, i.e., Update equip.ctl.

  1. If your old version was 9.12.10 or 9.12.11, you will need to add the final four lines of the example equip.ctl file to yours:

    cd /usr2/control
tail -n 4 /usr2/fs/st.default/control/equip.ctl >>equip.ctl

  2. If your old version was 9.12.12 or 9.12.13, you will need to insert two lines before the final two lines. This is covered in sub-step Review control files below.

  3. If your old version was 9.13.2, you will need to add the final two lines of the example equip.ctl file to yours:

    cd /usr2/control
tail -n 2 /usr2/fs/st.default/control/equip.ctl >>equip.ctl

3.14.4. Review control files

You should compare your versions of the following files:

  • clpgm.ctl

  • equip.ctl

  • stpgm.ctl

to the examples, e.g., using:

cd /usr2/control
diff clpgm.ctl /usr2/fs/st.default/control/ | less

and consider whether and what changes you should make to your copies.

The following sub-sections give the details of the changes in these files. You will need to make the corresponding changes to your copies of the files.

3.14.4.1. Review clpgm.ctl

You may be able to just replace your copy with the new one.

  1. Old versions 9.12.10 and 9.12.11:

    This file was not present so the new default version (copied by commands in sub-step Copy control files above) should not require modification.

  2. Old versions 9.12.12, 9.12.13, and 9.13.2:

    1. The -title …​ parameter for each window was removed so that it is uniquely supplied by the .Xresources file.

    2. The value of the -name parameter for erchk was changed from ERRORS to erchk.

    3. The useful display window scnch was added.

    4. The xterm program was added.

    5. For RDBE systems, the useful RDBE display windows: monit6, and monX (X=[a-d]) were added. The monan program was added to the default since it is used at several sites. If these are not relevant for your site, you may prefer to not add them.

3.14.4.2. Review equip.ctl
Caution
 This sub-step has the most complicated changes. Please read all clauses to make sure you see all that apply to your old version.

There are two sub-sections. The first sub-section covers changes to non-comment lines; the second, comments. The former are required. The later are in some sense optional, especially when they refer to equipment you don’t (or never will) have. However, changing them now may help avoid confusion at a later date.

Non-comment lines

  1. Old versions 9.12.10-9.12.13:

    1. The line for DBBC PFB version was changed to have a minimum version number of v15_1. The line is shown here with the typical preceding comment:

      *DBBC PFB version
v15_1    v15_1 or later

    2. The line that defines the DBBC2 CoMo configuration was changed. Please see item (12) in the installation instructions in /usr2/fs/misc/fs91119up.txt for full details on handling this. However, the following commands will probably make the needed change if you don’t have a DBBC2 or if your DBBC2 configuration is four CoMos with one Core per CoMo:

      cd /usr2/control
/usr2/fs/misc/dbbc_equip '1 1 1 1' equip.ctl

      If the script prints a warning about the number of IF power conversions being incorrect, the issue must be resolved before continuing, either by adjusting the number of power conversions, adjusting the CoMo configuration, or both.

  2. Old versions 9.12.10 and 9.12.11:

    A FiLa10G input select line was added, but sub-step Update equip.ctl above should have handled that.

  3. Old versions 9.12.12 and 9.12.13:

    A “stanza” (actually one comment and one FiLa10G input select line) was inserted before the final “stanza” (typically one comment and one DBBC3 configuration line). An example of the lines inserted can be found near the end of the default example /usr2/fs/st.default/control/equip.ctl file. They are listed here as well (one comment and one FiLa10G input select line):

    *FiLa10G input select, one of: vsi1, vsi2, vsi1-2, vsi1-2-3-4, gps, tvg
vsi1-2

  4. Old versions 9.12.10, 9.12.11, and 9.13.2:

    A new line for the DBBC3 configuration was added at the end, but sub-step Update equip.ctl above should have handled that.

Comment lines

  1. All old versions:

    Compared to all old versions, comment lines were added or modified for new equipment type options.

  2. Old versions 9.12.10-9.12.13:

    The trailing comment on the line for the met. device was reworded.

  3. Old versions 9.12.10-9.12.13:

    The comment lines describing the available clock rates was completely rewritten and greatly expanded, and an additional clock rate (128) was appended to the end of the comment on the clock rate line itself.

3.14.4.3. Review stpgm.ctl

  1. All old versions:

    Warning
    		 If you are not planning to use the FS display server, we recommend you comment out the lines for erchk, monit2, and scnch and not add any other monitX programs. If they are used in stpgm.ctl without the display server and they are accidentally closed, the FS will be killed.

    1. The line for erchk is now uncommented and differs from the previous commented version with the addition of the -name erchk parameter and the removal of the -title …​ and -geom …​ parameters, so that the latter two are uniquely supplied by the .Xresources file.

    2. New lines were added for monit2, and scnch for when the display server is in use.

      If you are using the display server you may want to add other monitX programs. If so, you may also want to add resources for them (if they aren’t already there) in the ~/.Xresources files for oper and prog.

3.14.5. Update rdbemsg.ctl

  1. Versions 9.12.10-9.12.13:

    If you have RDBEs for your back-end and will use the rdbemsg utility to send operations messages, you will need to customize your /usr2/control/rdbemsg.ctl file.

    1. You will need to update the station two letter code (lower case) and the name station name to your station’s values. The station name is usually defined in the /usr2/control/location.ctl file.

    2. If you don’t have a HubPC (mci) node for front end monitor and control, you should comment out that line.

    3. You should set the addresses for the RBDE-A (R-A) through RDBE-D (R-D). The example file uses aliases, rdbea through rdbed, that you can define in /etc/hosts. Likewise, if you have an mci node, you should set its alias, hubpc, in /etc/hosts. (It is usually necessary to have root access to modify /etc/hosts.) Alternatively of course, you can use any scheme you prefer for defining these addresses in rdbemsg.ctl.

    4. The default email address to is for the ivs-vgos-ops mail list. You can of course change that to whatever you like. You can also temporarily override the address in the rdbemsg utility itself.

3.15. Update .prc files

This step is for updates to your SNAP .prc procedure libraries. The are two sub-steps. Only the change in the first is required: converting from using the old FS go program to rte_go. The change in the second is optional and only relevant if upgrading from 9.13.2: removing if=cont_cal,, from the fivpt and onoff procedures for calon and caloff procedures.

3.15.1. Convert from go to rte_go

Convert use of the old FS go program to use rte_go. This is required because the compiler for the go language conflicts with the old program name go. This change is necessary even if you do not have the go language compiler installed.

To make this change for all your .prc procedure libraries, execute:

cd /usr2/proc
/usr2/fs/misc/go_fix *.prc

Files that are changed will have a pre-change back-up copy with the extension .bak. You can use the .bak file to recover in case of a problem.

3.15.2. Remove extra if commands

This sub-step is optional and only relevant if you are upgrading from 9.13.2. You can remove the if=cont_cal,, as a prefix from before the calon and caloff commands in you calonnf, calonfp, caloffnf, and calofffp procedures, probably located in your point procedure library. This is just a clean-up and not making this change will have no impact.

3.16. Miscellaneous FS related changes

There are two changes: set the FS_DISPLAY_SERVER environment variable for oper and prog (this is only needed if you were not running the FS display server before) and update the ~/.Xresources file for the oper and prog accounts.

3.16.1. Set FS_DISPLAY_SERVER

Set the FS_DISPLAY_SERVER environment variable for oper and prog. This will make using the display server the default for your system. We strongly recommend this, but if it is not suitable for you for some reason you can skip this. If you are already using the display server, you can also skip this sub-step.

Warning
 If you don’t use the display server, you will probably need to update the stpgm.ctl file for that case as described in sub-step Review stpgm.ctl above.

If oper uses the bash shell then in the ~oper/.profile file, you can uncomment or insert

export FS_DISPLAY_SERVER=on

If oper uses the tcsh shell then in the ~oper/.login file, you can uncomment or insert

setenv  FS_DISPLAY_SERVER on

You should logout and login again after making this change.

You should make the corresponding change for prog while logged in as prog.

3.16.2. Update .Xresources

The main change was to add values for the erchk, scnch, and helpsh windows. There were some minor changes for other windows, but what to use for the changed values may depend on the resolution of your display. The example values worked well for an FSL10 installation on a system with a non-GPU CPU.

Tip

A strategy for setting the geometry resource for a window is:

  1. Adjust the position (and maybe the size) of the window to what you want.

  2. Run the xwininfo program

  3. Position the cursor on the window and click.

  4. Copy the string output for the -geometry parameter, e.g, 80x24+0+0.

  5. Paste the string as the value for geometry resource for that window in the ~/.Xresources file.

You will need to logout and login again (or reload the X resources a different way) for the change to become effective.

As oper, you can find the differences between your file and the example file with:

cd
diff .Xresources /usr2/fs/st.default/oper

Please make any changes to your file that you find appropriate, but at a minimum you should probably add the lines for monit6, erchk, scnch, and helpsh if not already present. You will need to logout and login again (or reload the X-resources a different way) for the changes to become effective.

All the new lines are at the end of the file, if need to add lines for monit6, erchk, scnch, and helpsh, you can use:

cd
tail -n 24 /usr2/fs/st.default/st.default/oper/.Xresources >>.Xresources

To add lines for just erchk, scnch, and helpsh, you can use:

cd
tail -n 20 /usr2/fs/st.default/st.default/oper/.Xresources >>.Xresources

To add lines for just helpsh, you can use:

cd
tail -n 6 /usr2/fs/st.default/st.default/oper/.Xresources >>.Xresources

You can update prog's .Xresources file similarly, but you will need to be logged in as prog.

3.17. Miscellaneous FSLx changes

None are required for this update.

3.18. Test the FS

Generally speaking, a fairly thorough test is to run a test experiment. Start with using drudg to rotate a schedule, drudging it to make .snp and .prc files, making listings, and any other pre-experiment preparation and tests you normally do, then execute part of schedule, and perform any normal post-experiment plotting and clean-up that you do. The idea here is to verify that everything works as you expect for normal operations.

3.19. Consider when to update your back-ups

Warning
 This step may not be appropriate if you are beta testing since the beta test versions are not intended for operations.

It would be prudent to wait until you have successfully run an experiment or two and preferably received word that the experiment(s) produced good data. The chances of needing to use your back-up should be small. If something does happen, you can copy the back-up to the (now assumed bad) updated disk. You can then either use the restored disk or apply the FS update again. The FSL10 test procedure has more options for recovery. Managing this is a lot easier and safer if you have a third disk.

4. Changes from FS9

There are separate sub-sections with summaries of changes in the FS and drudg. Following those are sub-sections giving the details of the changes. Each summary item has a clickable More details link that leads to the detailed description of that item.

Each sub-section is divided into three parts:

  1. Changes that are in common since FS9

    These parts cover changes compared to both FS9 branches. These are changes that have been introduced in version 10.0.0.

  2. Changes relative to the main branch

    These parts cover changes that are only relative to the main branch, specifically version 9.13.2. These are primarily features that were in the VGOS branch but not in the main branch.

  3. Changes relative to the VGOS branch

    These sparts cover changes that are only relative to the VGOS branch, specifically version 9.12.13. These are primarily features that were in the main branch but not in the VGOS branch.

Clickable links such as #36 connect to specific issues reported at https://github.com/nvi-inc/fs/issues.

A complete history of changes can be found using the git log command.

The file /usr2/fs/misc/changes.txt contains the old history of changes in FS9. The file /usr2/fs/misc/VENIX_changes.txt contains the old history of changes in FS8. However these two files have been merged into the history given by git log.

The history of drudg is also described in more detail in /usr2/fs/drudg/change_log.txt.

4.1. Summary of FS changes

This sub-section is divided into three parts. Please see Changes from FS9 above for an explanation of the parts.

4.1.1. Changes that are in common since FS9

  1. One unified version for all FS users. More details.

  2. Support for use on both 32- and 64-bit systems. More details.

  3. Version control with git. More details.

  4. The FS uses a new Makefile scheme. More details.

  5. Improve fesh (includes closing #34). More details.

  6. Update example equip.ctl (includes closing #35). More details.

  7. Fix some error messages (includes closing #43 & #22). More details.

  8. Improve plog. More details.

  9. Restore if command. More details.

  10. Update GPL in files. More details.

  11. Remove usage of system() call to find help file_(closes #40 & #3). More details.

  12. No longer set /usr2/fs and /usr2/st to be owned by prog. More details.

  13. Add checking for a procedure or schedule file before attempting to open it (closes #45). More details.

  14. Add more log header lines. More details.

  15. Fix year wrap error message in procedure logging (closes #23). More details.

  16. Fix remaining case of a closed procedure library causing a crash if there was an attempt to execute a procedure from the library was fixed. More details.

  17. Move X resources for helpsh to ~/.Xresources. More details.

  18. Move unsetting of TMOUT environment variable for oper to ~/.bashrc in the default files. More details.

  19. Improve error logging for dbbcn. More details.

  20. Improve help page for tpicd. More details.

  21. Add popen time-out feature. More details.

  22. The FS display server is now recommended for normal use. More details.

  23. Make fsclient honor the -n flag properly (closes #48). More details.

  24. Make fsclient ignore prompt in no-X11 mode (closes #49). More details.

  25. Add fsserver improvements and log support (includes closing #29 & #25). More details.

  26. Eliminate cls_chk error from inject_snap -w …​ command when an error occurs (partly closes #50). More details.

  27. Fix labels in gnplt windows that display the gain curve coefficients (closes #51). More details.

  28. Improve holog/MASK. More details.

  29. Fix onoff for the DBBC3 rack (closes #52). More details.

  30. Add support for DBBC3 to if=cont_cal,…​ (closes #54). More details.

  31. Update help pages for onoff and fivpt. More details.

  32. Always check for day 248 problem in setcl (closes #56). More details.

  33. Change the flags for the monX programs in clpgm.ctl from a to d. More details.

  34. Generalize the scnch window to cover Mark 5 recorders (closes #61). More details.

  35. Update misc/release_model.txt. More details.

  36. Improve update notes. More details.

4.1.2. Changes relative to the main branch

TODO: Complete this sub-section.

  1. Input is now case sensitive. More details.

  2. tpicd=no requires a running (not halted) schedule to log data. More details.

4.1.3. Changes relative to the VGOS branch

TODO: Complete this sub-section.

4.2. Summary of drudg changes

This sub-section is divided into three parts. Please see Changes from FS9 above for an explanation of the parts.

4.2.1. Changes that are in common since FS9

drudg opening message date is 2020Jun30.

  1. Source code now works on 32- and 64-bit platforms. More details.

  2. Source version control is maintained with git. More details.

  3. Fix uninitialized variables. More details.

  4. Fix missing preob when EARLY start non-zero. More details.

  5. Add support for additional wait at the end of recording for broadband. More details.

  6. Update comment on line three of .snp files. More details.

4.2.2. Changes relative to the main branch

TODO: Complete this sub-section.

4.2.3. Changes relative to the VGOS branch

TODO: Complete this sub-section.

4.3. Details of FS changes

This sub-section is divided into three parts. Please see Changes from FS9 above for an explanation of the parts.

4.3.1. Changes that are in common since FS9

  1. One unified version for all FS users.

    Both non-VGOS and VGOS operations are supported by the new version. Previous installations of the main (non-VGOS) branch will need to have some new local control files added.

    The most significant change for users is that previous main branch users will find that in the new FS input is case sensitive, as it was already in the VGOS branch.

  2. Support for use on both 32- and 64-bit systems.

    The new version should run on 32-bit systems that currently support the FS (we expect to support as far back as FSL8, but currently FSL9 is the limit), as well as on 64-bit systems. The Converting to a 64-bit system document contains instructions for transitioning to a 64-bit system.

    The key change to the source code to make this compatibility possible is avoiding use of long ints, except where they are required for system calls, particularly in fixed length data structures. A tool, unlongify was developed by Dave Horsley to help convert the FS code. It is available to help convert station code. It use is described in the Conversion of C code sub-step of the Converting to a 64-bit system document.

  3. Version control with git.

    The FS source is now managed using git and github is used for distribution. The source code is now under the GPL3 license.

    The details of the model used for FS releases under git are described in the Release Model document.

    This change increases the importance of not modifying the /usr2/fs directory tree since such changes will make it more difficult to simply pull updates to install bug fixes and new features.

  4. The FS uses a new Makefile scheme. This is accomplished by including the /usr2/fs/include.mk file in every Makefile except for drudg and its libraries. The scheme is “opt-in” so it is not necessary for every program or station programs to participate. Within the FS source tree, only drudg and its libraries don’t use it. An explanation of the new scheme is provided in /usr2/fs/misc/fs10_makefile.md.

  5. Improve fesh (includes closing #34).

    1. A typo in the error message for when the schedule is already downloaded was fixed (closes #34). Thanks to Morgan Goodrich (KPGO) for reporting this.

    2. The internal version number was replaced with the FS version.

  6. Update example equip.ctl (includes closing #35).

    1. The example DBBC3 firmware version is now more sensible (closes #35). Thanks to Eskil Varenius (Onsala) for reporting this.

    2. The minimum DBBC3 firmware version required was added in a comment.

  7. Fix some error messages (includes closing #43 & #22).

    1. Fixed errors in control/fserr.ctl. Errors in some double double-quotes ("") lines and some incorrectly reused error codes were fixed (closes #43). Thanks to Alexander Neidhardt (Wettzell) for reporting these.

    2. The errors for a tnx command not being found when attempting to manipulate its display setting were clarified (closes #22). Thanks to Jon Quick (HartRAO) for reporting this.

    3. Error messages that should refer to the (not yet implemented) active_rdbes and active_mk6s commands were corrected to no longer incorrectly refer to the rdbe_active and mk5_active commands, respectively.

    4. Obsolete errors for the, no longer used, sw.ctl control file were removed.

  8. Improve plog.

    1. Use of an environment variable NETRC_DIR was added to support not having the .netrc file in the user’s home directory was added. Please see plog -h for details on how to use this.

    2. The internal version number was replaced with the FS version.

  9. Restore if command. It had accidentally been overlooked in beta1. Thanks to Beppe Maccaferri (Medicina) for reporting this.

  10. Update GPL in files. The GPL header was added to the holog/MASK/*.m and misc/mk6in* scripts and removed from fserver/tests/convey.*.

  11. Remove usage of system() call to find help files (closes #40 & #3). The help command no longer uses the system() to find the correct help file to display.

  12. No longer set /usr2/fs and /usr2/st to be owned by prog. This was an error in the misc/fsinstall script.

  13. Add checking for a procedure or schedule file before attempting to open it (closes #45). This change is to avoid accidentally closing an active procedure or schedule file if the new one specified in the proc=…​ or schedule=…​ commands, respectively, does not exist (or has incorrect permissions). Previously, if the files did not exist (or did not have the correct permission), the old file would be closed. Thanks to Jon Quick (HartRAO) for pointing out this inconsistency.

    The old behavior was partly a consequence of how the original file handling worked on HP-RTE systems, but is not sensible for how the SNAP commands should work. Note that this is a non-backward compatible change in how the SNAP commands behave. Previously supplying a non-existent procedure or schedule file name would cause the closure of the corresponding file. Now to close an open procedure or schedule without opening a new one, a null parameter must be supplied, i.e., proc= or schedule=. As before, the latter will not close an open schedule procedure library.

  14. Add more log header lines. Log header lines were added for uname() system information and the compile time value of the FC environment variable.

  15. Fix year wrap error message in procedure logging (closes #23). This fixed a benign and spurious error message if a log was kept open past the end of the year and any procedures that had last been logged in the previous year were executed again. Thanks to Eskil Varenius (Onsala) and Alexander Neidhardt (Wettzell) for reporting this.

  16. Fix remaining case of a closed procedure library causing a crash if there was an attempt to execute a procedure from the library was fixed. This case could happen if the schedule that was opened was named station, which would lead to the closure of an already open schedule procedure library (there cannot be station schedule procedure library since station can only be opened once).

  17. Move X resources for helpsh to ~/.Xresources. This allows the geometry and other parameter of the FS help display xterm to be controlled locally.

  18. Move unsetting of TMOUT environment variable for oper to ~/.bashrc in the default files. This allows all interactive shells to disable the time-out. Additionally, some settings were rearranged in ~/.bashrc to make them only apply to interactive shells (this was also done for prog and AUID accounts). This change is only relevant for stations using FSL10.

  19. Improve error logging for dbbcn. The name of the program is now correctly displayed.

  20. Improve help page for tpicd. Made it clearer that when in the no mode, data_valid=on will only start logging of tpicd data when a schedule is running and not-blocked. This behavior was inherited from the VGOS branch where accidentally leaving tpicd logging RDBE multi-cast data after closing a schedule or halting it creates a lot of extra log entries. This is probable beneficial for all back-ends.

  21. Add popen time-out feature. There is a now a -t …​ time-out option. If the command being run has a time-out feature, it is generally better to use the command’s feature. See help=sy for more details.

  22. The FS display server is now recommended for normal use. This was changed as of the beta2 release.

  23. Make fsclient honor the -n flag properly (closes #48). This eliminates opening “double” windows if fsclient is run with -n under an already running fsclient.

  24. Make fsclient ignore prompt in no-X11 mode (closes #49). If FS client is in no-X11 mode, it created a fs.prompt when instructed by the server. This change removes that behaviour, though it may cause an issue if no other clients exist to dismiss the prompt, see issue #49. If this is a problem for anyone’s use case we will need a new feature here.

  25. Add fsserver improvements and log support (includes closing #29 & #25). These changes introduce new functionality to fsserver, as well as simplifies some use cases.

    1. The first major change is that the server now only needs to use one socket when using websockets — address which start with ws:// (closes #29). The new default base URL for all fsserver streams and control channels is now:

      ws://127.0.0.1:7083

      (70 83 are decimal ASCII encoding of F and S.)

      This can be changed by editing FS_SERVER_URL_BASE in include/params.h; however, we will likely introduce command-line flag and/or environment variable to set this in the future.

      This is should be safe to expose on the network (rather than just the loop-back), but users may wish to use an HTTP(S) as a proxy to provide some authentication/authorisation.

      This was enabled by factoring out functionality spub into a reusable “buffered stream” library, which has been incorporated into fsserver. All the behaviour of streams are now managed within the fsserver process rather than an external spub instance.

    2. The second major change of this patch is the addition of the FS log to the streams available from the server (closes #25). (Previously only the “display” was available, which has a reduced time-stamp format and filters some output.)

      This is available at

      FS_SERVER_URL_BASE/log

      that is, by default

      ws://127.0.0.1:7083/log

    3. A third change is that the server now continues running after the FS is terminated. This allows clients to detect the FS termination and prevents a socket conflict if the FS is terminated and restarted in quick succession. The only user visible impact will be a slight delay if the FS is restarted quickly after termination while the old session is finishing up. This also means, after an FS upgrade, it’s important to either shutdown the server (fsserver stop) or restart the system.

    4. Fourth, the server can now accept snap commands to be sent to FS, e.g.:

      fsserver fs snap "terminate"

      This allows clients to interact with the FS directly through fsserver rather than needing access to inject_snap.

      No filtering or authorisation is implemented on this command channel, so it effectively allows complete command execution privileges in the FS context to anyone with access to the socket. Note this is also true for inject_snap on a standard system. If a station wishes to limit local access they can use iptables/nftables, or use the server in UNIX socket mode and use file system permissions. Stations that would like to enable remote access should implement their own authentication/authorisation that suits their needs, e.g. SSH port forwarding or HTTP proxying.

    5. Finally, this patch also upgrades the included messaging library nng to version 1.3.0, which brings with it some performance improvements and bug fixes, the most obvious to FS users caused some ssub instances in “wait” mode to use a high amount of CPU time.

  26. Eliminate cls_chk error from inject_snap -w …​ command when an error occurs (partly closes #50). This was caused by inject_snap not implementing the new linkage that was added for fserr. This is covered in issue #50. To correctly retrieve the error message would have required making a new interface to fserr or subsuming it into library routine that both ddout and inject_snap could use. It was not possible to do either in the available time. Instead inject_snap was modified to output the error without the message, but pointing out that the message can be found in the log and display. Thanks to Dave Horsley (Hobart) for reporting this.

  27. Fix labels in gnplt windows that display the gain curve coefficients (closes #51). Previously the labels, when displayed were in reverse order. In one window, there were no coefficient labels at all. Thanks to Beppe Maccaferri (Medicina) for reporting this and testing the solution.

  28. Improve holog/MASK. The elevation spacing was corrected for the example in step (3), using holog.m. Axis titles were added to plot_mask.m.

  29. Fix onoff for the DBBC3 rack (closes #52). A code block from 9.12.13 in onoff/get_samples.c had been omitted, preventing sampling of the TPI values and causing onoff to crash. Thanks to Eskil Varenius (Onsala) for reporting that this caused a crash.

  30. Add support for DBBC3 to if=cont_cal,…​ (closes #54). Thanks to Eskil Varenius (Onsala) for reporting that this was missing.

  31. Update help pages for onoff and fivpt. Added a section on switching between continuous and non-continuous cal. Removed if=cont_cal,, in calon/off-nf/fp procedures. Add recovery method for misconfigured cal.

  32. Always check for day 248 problem in setcl (closes #56). Previously setcl only checked for the day 248 problem (due to use of 32-bit arithmetic in the time handling code), if the time model was not computer. In principle, when the model is computer there is no need to check for this issue. However, since the time is still managed with the same 32-bit arithmetic as for the non-computer models, it is still necessary to check. Not doing so was an oversight. The result was that there were no warnings of an impending 248 day time problem if the model was computer. This is now fixed. Thanks to Richard Blaauw (WSRT), and subsequently Jon Quick (HartRAO) for reporting this.

  33. Change the flags for the monX programs in clpgm.ctl from a to d. Since they do not depend on the FS, they can continue running after the client is closed.

  34. Generalize the scnch window to cover Mark 5 recorders (closes #61). The scnch window was initially developed for Mark 6 recorders. The form has now been generalized to cover Mark 5 recorders as wekk

  35. Update misc/release_model.txt. The release steps were clarified.

  36. Improve update notes.

    1. The -q option was added to the pull to suppress the detached HEAD warning.

    2. A sentence was added to the description of the change to using git that it now even more important to not change the contents of the /usr2/fs source tree. Changing the source tree will make it harder to install bug fixes and updates.

    3. The paths to the example control files now include the needed intermediate directory fs/.

    4. The sub-steps for updating the control files were corrected to properly depend or not depend on the old version being 9.12.12.

    5. A sub-step was added to make using the FS display server the default.

    6. A sub-step was added for updating the ~/.Xresources file for oper and prog.

    7. A sub-step to update where the TMOUT environment variable is unset for stations using FSL10 was added.

    8. A recommendation was added to sign-up for the go language announcements to be informed of security updates if you are installing the latest version of go lnaguage.

4.3.2. Changes relative to the main branch

TODO: Complete this sub-section.

  1. Input is now case sensitive. As was the case for the VGOS branch, operator, schedule, and procedure is now case sensitive. This change should present no difficulties if all normal input is in lower case. All SNAP commands and most parameters are lower case.

    The change was made because in some cases it necessary to send upper or mixed case input to devices and other computers from SNAP commands. For MAT and GPIB communication, all communications sent to the devices is still mapped to upper case.

    The biggest consequence of this change is perhaps that strings sent in antenna=…​ commands to the antenna are not by default be mapped to upper case. If this an issue for a particular antenna, it may require changes to your antcn program. This is covered in the Case sensitive strings in antenna= commands sub-step of the Update station programs step above.

  2. tpicd=no requires a running (not halted) schedule to log data. This changes was introduced from VGOS branch, where it critical to avoid logging very large amounts of data for RDBE systems if the schedule ends or is halted while tpicd is recording data. It is probably beneficial for all back-ends, so has been made a general feature.

4.3.3. Changes relative to the VGOS branch

TODO: Complete this sub-section.

4.4. Details of drudg changes

This sub-section is divided into three parts. Please see Changes from FS9 above for an explanation of the parts.

4.4.1. Changes that are in common since FS9

  1. Source code now works on 32- and 64-bit platforms. The use of FORTRAN requires eight-byte integers to support some calls in the VEX library. As a result the drudg program has its own version of the lnfch library, skdrlnfch, which uses eight byte integers, as does the skdrutil, as well as drudg itself. The rest of the FS uses four byte integers by default.

  2. Source version control is maintained with git. The drudg program is external to the FS. For each drudg update the source in imported into the FS git repo for distribution with the FS. This does not provide the same level of tracking as having drudg itself in git but it is still useful.

  3. Fix uninitialized variables. Several previously uninitialized variables are now initialized. As part of this implicit none was added to all FORTRAN routines that did not have it before, except for xat.f.

  4. Fix missing preob when EARLY start non-zero. This was broken in the implementation of staggered start for FS 9.13.0 and has been restored.

  5. Add support for additional wait at the end of recording for broadband. This allows schedules to include a fixed amount of additional wait for buffering per station. This seems to be needed for Mark 6 recorders in configurations that otherwise would require no buffer time for disks that are slower than nominal.

  6. Update comment on line three of .snp files. Previously at the end of line, the number of passes and the tape length were listed. Since there is no tape support, these fields were replaced with the recorder type.

4.4.2. Changes relative to the main branch

TODO: Complete this sub-section.

4.4.3. Changes relative to the VGOS branch

TODO: Complete this sub-section.