1. Introduction

The document covers updating from the beta2 pre-release to the beta3 pre-release.

For instructions for other upgrade paths, see the Other update documents sub-section of the FS 10.0.0 Update Notes document.

2. Upgrading from 10.0.0-beta2 to 10.0.0-beta3

You must have already upgraded to 10.0.0-beta2 according to the FS 10.0.0-beta2 Update Notes document or the FS 10.0.0-beta1 to FS 10.0.0-beta2 Update Notes before installing this update.

2.1. Fetch and make 10.0.0-beta3

Note
 If you are using FSL7 or other old distribution that may not be compatible with the latest update of the server, you may still be able to use the FS without the server by removing it from the make process. Please follow the steps in not building the display server below.

If you are using git, as is recommended, then as prog execute:

cd /usr2/fs-git
git fetch
git checkout -q 10.0.0-beta3
make clean rmdoto rmexe
make >& /dev/null
make -s

No output from the last command indicates a successful make.

2.2. Additional steps

  1. If you use RDBEs in your back-end and want to use the rdbemsg utility to send operations messages, please customize your /usr2/control/rdbemsg.ctl control file by adding the name line to the file if you haven’t already. Full instructions are provided in the, revised, Update rdbemsg.ctl sub-step in the beta2 update notes document.

  2. If you use the fesh script there is one required change (listed first below) and a few optional changes that depend on your situation:

    1. If not already set, specify a directory for .skd files in the $schedules block of the /usr2/fs/skedf.ctl control file. You can use any value you want, but to be backward compatible with the previous behavior of fesh it must be /usr2/sched.

    2. Likewise, directories should be specified in the $snap and $proc blocks of /usr2/contol/skedf.ctl. You can use any values you want, but typically they should be set to /usr2/sched and /usr2/proc, respectively, to agree with the FS.

    3. The fesh script uses cddis as the default data center. You can specify a different data center by setting the FESH_DATA_CENTER environment variable. Available data centers for geodesy are bkg, cddis, and opar; for astronomy, vlbeer.

      Tip
      		 For FSL8 and other old Linux distributions, access to cddis may not be possible, due to out-of-date certificates. If you are in that situation, bkg or opar may be suitable alternatives.

    4. The fesh script uses FTP-SSL as the default access method for the cddis data center. For this case, you an avoid having to answer a prompt for your email address each time you run fesh by setting your email address in the FESH_EMAIL environment variable.

      Tip
      		 The FTP-SSL method may not work from behind some firewalls. If it doesn’t work for you, either use a different data center (see above) or use HTTPS for cddis (see below).

    5. You can change the access method for cddis to HTTPS, by setting the FESH_CDDIS_METHOD environment variable to https.

      Note
      		 Using HTTPS requires an EarthData login and setting it in your .netrc file. If you don’t have an EarthData login, you should be able to get one by selecting REGISTER at: https://urs.earthdata.nasa.gov/.

    Please see fesh -h for more information on using these features. A more complete description of the changes is in fesh changes below.

  3. If you have a local (station) lo command, you will need to update it (or replace it, see the next paragraph) to get full support for rack types that were not in your previous FS9 version and implement the new capability described in logging .rxg files below.

    To reduce the maintenance burden of updating your local lo (and, if you have it, an lo_config) command in the future, you should consider switching to use the newly provided lo command hooks described below. This approach may not be suitable for all stations, but if it will work for your station, it should reduce, and in most cases eliminate, the need to update your local software when the FS lo command changes in the future.

  4. Update /usr2/control/skedf.ctl. Due to an error in the example /usr2/fs/st.defaut/control/skedf.ctl file, most stations probably incorrectly show the lo_config keyword as if_config in their local version. Please check your local copy and update any occurrences, even in comments, of if_config to lo_config.

2.3. Review other changes

Please see the sub-section Changes since 10.0.0-beta2 below for details of the changes since that release.

3. Changes since 10.0.0-beta2

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.

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.

3.1. Summary of FS changes

  1. Add new_ifdbb script for (RDBE) VGOS stations. More details.

  2. Update and expand fesh (includes closing #36, #37, #65, and partially closing #38). More details.

  3. Remove hard coding of the station name in rdbemsg (closing #62). More details.

  4. Improve fsserver (includes closing #69, #78, and re-closing #76). More details.

  5. Improve gnplt (closing #72 and #73). More details.

  6. Improve help command (includes closing #75). More details.

  7. Add option to not build the display server into the FS (partially closing #76). More details.

  8. Add GPL to files. More details.

  9. Improve update notes (includes closing #71). More details.

  10. Add .rxg file logging to lo command. More details.

  11. Add hooks for local LO control to lo and lo_config commands. More details.

  12. Fix example /usr2/fs/st.default/control.skedf.ctl (closing #81). More details.

  13. Fix ignoring antcn errors in the satellite and satoff commands. (closing #82). More details.

3.2. Summary of drudg changes

drudg opening message date is 2020Sep14.

  1. Fix crash if $HEAD is the last block in a .skd file. More details.

  2. Fix crash if error in mask (closing #74). More details.

  3. Clean-up source. More details.

3.3. Details of FS changes

  1. Add new_ifdbb script for (RDBE) VGOS stations. This script is intended as a tool to allow stations, and schedule writers, a way to update schedules for changes in the ifdbb procedure used by VGOS stations, particularly those with RDBE back-ends. For RDBE stations, the attenuation used in the signal chain, which is set by the schedule, depends on the observing mode being used and the conditions at the station. The provides a way to incorporate needed changes into schedules. If the script is run without other command line arguments, it will output “help” information.

  2. Update and expand fesh (includes closing #36, #37, #65, and partially closing #38).

    1. fesh now supports encrypted access to cddis using FTP-SSL and HTTPS (closing #36). This allows use of cddis after non-SSL FTP access was disabled there at the end of October 2020. FTP-SSL is the default method.

      For FTP-SSL, it is recommended that the FESH_EMAIL environment variable be set to avoid having to provide an email address as the anonymous FTP-SSL password for each invocation.

      Tip
      		 The FTP-SSL method may not work from behind some firewalls. If it doesn’t work for you, you can either use HTTPS for cddis or use a different data center (see below).
      Caution
      		 The use of FTP-SSL by cddis may be deprecated in the future.

      Using HTTPS can be activated for cddis by setting the FESH_CDDIS_METHOD environment variable to https.

      Note
      		 Using HTTPS for cddis requires an EarthData login and setting it in your .netrc file. If you don’t have an EarthData login, you should be able to get one by selecting REGISTER at: https://urs.earthdata.nasa.gov/.
      Tip
      		 For FSL8 and other old Linux distributions, access to cddis may not be possible, due to out-of-date certificates. If you are in that situation, bkg or opar may be suitable alternatives.

    2. fesh now supports bkg, cddis, opar, and vlbeer data centers (closing #37). The data center can be selected with the FESH_DATA_CENTER environment variable or the -D command line option. The default data center is cddis. For vlbeer only .vex files are supported; for the others only, .skd. Running drudg automatically is not supported for vlbeer.

    3. fesh now respects the /usr2/control/skedf.ctl control file (closing #65). Previously fesh assumed that the directory for .skd files was /usr2/sched/ regardless of what was in the $schedules block of /usr2/control/skedf.ctl. This only worked if the directory specified was /usr2/sched or was the working directory (i.e., not specified or .). This prevented use with different directories, such as /usr2/exper, for .skd files. Thanks to Jon Quick (HartRAO) for reporting this.

    4. fesh now provides support for drudg optional prompts for geodesy schedules (partially closing #38). It is assumed that for geodesy the answers to these questions for a station do not vary. This feature is intended to allow stations that observe both astronomy and geodesy schedules to use fesh for geodesy schedules. The environment variables FESH_GEO_TPICD, FESH_GEO_CONT_CAL, FESH_GEO_CONT_CAL_POLARITY, and FESH_GEO_VSI_ALIGN or the command line options -tcpa can be used to supply answers to the corresponding drudg prompts.

      Important
      		 Let the user beware. This feature must be used with extreme care. The answers that are specified must correspond exactly to the questions that drudg will ask. If they don’t correspond correctly, drudg may produce subtly incorrect output with no obvious indication of a problem. The fesh script does what consistency checking it can, e.g., if FESH_CONT_CAL is specified as off, no answer can be supplied for FESH_CONT_CAL_POLARITY since that question will not be asked. It is important to verify that correct output is being produced.
      Important
      		 The feature will not work for schedules that have more than mode. It is extremely rare for geodesy schedules to have more than one mode, but it is possible.

    5. Use of an environment variable, LIST_DIR, was added to specify the directory for drudg listings. If not set, the .skd file directory is used.

    6. Use of an environment variable, NETRC_DIR, was added to specify a directory other than the user’s home directory (~) for the .netrc file used with HTTPS access for cddis. The same variable is used by the plog script for the same purpose.

      Normally, the .netrc file would be in the user’s home directory. However, some systems have security policies that forbid that. This variable provides a way to have the .netrc file in a different directory.

    7. The user name for the unencrypted FTP access to bkg, opar, and vlbeer, is explicitly set to ftp to avoid potential conflicts with other accounts specified in ~/.netrc (this is not redirected by NETRC_DIR).

    8. Several new command line options were added:

      1. -y to override the year directory accessed for a geodesy data center (the default is the current year).

        This is particularly useful for getting schedules for the next year.

      2. -t to trigger also downloading the .txt file associated with a geodesy schedule.`

      3. -m to override the month directory accessed for vlbeer (the default is the current month).

        This is particularly useful for getting schedules for a future month.

      4. -H to disable the default use of the .latest sub-directory of the month directory for vlbeer.

      5. -D to override the data center if the FESH_DATA_CENTER environment variable is set, or change the data center from the default if it is not set.

      6. -s to override the station code if the STATION environment variable is set, or set it if it is not set.

    Please see fesh -h for more information on using these features.

  3. Remove hard coding of the station name in rdbemsg (closing #62). The station name is now set in rdbemsg.ctlr control file. Thanks to Chevo Terraza (MGO) for reporting this.

  4. Improve fsserver (includes closing #69, #78, and re-closing #76).

    1. spub/ssub occasionally froze (closing #69). This may have been caused be the byte order being wrong in buffered stream cb We believe that this issue is fixed. The situation is still being monitored. Please report any instance of this problem that occurs. It happens very rarely so it is challenging to get enough usage to verify that it is not happening. If it does happen, restarting the client has been a successful strategy for recovery.

    2. Fixed clean function in Makefile.

    3. Fixed sspub to support more than 232 messages.

    4. Modified the build so that it will work for FSL8 (closing #78, and re-closing #76). Thanks to Jon Quick (HartRAO) for special effort on this including adding documentation to assist with future upgrades of nng.

  5. Improve gnplt (closing #72 and #73).

    1. gnplt now updates the date in updated .rxg files (closing #72). The original developer, Tomas Gille (NVI), did very good work developing this second version of gnplt, but ran out of time in his internship and was unable to include this minor but important feature. Thanks to Beppe Maccaferri (Medicina) for reporting this.

    2. gnplt now works on FSL8 (Lenny) again (closing #73). Some improvements in beta1 made it fail for FSL8.

  6. Improve help command (includes closing #75).

    1. The help file for the ddbc command was expanded to also describe the dbbc2 and dbbc3 commands and now includes a description of the output for multi-line responses for all of these commands (closing #75). The help command now works for the dbbc2 and dbbc3 commands.

    2. The help file for the fila10g command was expanded to also support the fila10g2 command. The help command now works for the fila10g2 command.

    3. Restore help command for DBBC3 commands. The selection of DBBC3 specific commands was lost in the merge of the VGOS and main branches. It is now restored.

  7. Add option to not build the display server into the FS (partially closing #76). The latest version of the server may not make successfully on some older Linux distributions such as FSL7. To help users in that situation, an option was added to disable inclusion of the server by setting the FS_DISPLAY_SERVER_NO_MAKE environment variable before make-ing the FS. Follow the steps below to remove the server.

    1. As prog:

      • If you use tcsh, add the following to ~/.login:

        setenv FS_DISPLAY_SERVER_NO_MAKE 1

      • If you use bash, add the following to ~/.profile:

        export FS_DISPLAY_SERVER_NO_MAKE=1

    2. Logout of and then back into the prog account.

    3. make the FS.

    4. It is also necessary to make sure that users running the FS do not have the FS_DISPLAY_SERVER environment variable set.

      1. As oper:

        1. Delete or comment out any lines in the ~/.login file (if using tcsh) or ~/.profile (if using bash) setting the variable.

        2. Logout and back in before attempting to run the FS.

      2. Repeat the above steps as prog.

  8. Add GPL to files. The GPL was missing from the include/*.i files.

  9. Improve update notes (includes closing #71).

    1. Modify steps for updating to a specific commit after beta2 to use the latest commit instead. As well as being simpler, this is part of a new approach to try to keep the update notes current with the latest commit. It is important to be aware that the latest commit is not a version intended for operations. We make every effort to make sure it is bug free, but problems may occur. Since it represents the “bleeding edge” of development, features may not be as stable nor use as reliable as released (tagged) versions.

    2. Add the inclusion of the new rdbemsg utility as a change. It was not mentioned for beta1 or beta2.

    3. Add missing rdbemsg.ctl customization.

    4. Reorganized as .adoc files in the docs/ sub-directory (closing #71).

      All of the .adoc files are viewable as HTML, and are hierarchically indexed, at https://nvi-inc.github.io/fs/. The first update notes available in HTML are for 10.0.0-beta2. Hopefully, this change will make the update notes easier to read and navigate. Among other improvements, there are clickable links to other sections within documents as well as to sections in other related documents. FS Document Font conventions similar to the traditional printed FS manuals are used. A document describing FS environment variable use was added.

    5. Improve structure and correct some errors from original .txt version.

    6. Some typo/wording fixes.

  10. Add .rxg file logging to lo command.

    1. Summary information logging.

      When an LO is configured (or monitored) with the lo command, a summary of information from the matching .rxg file is displayed and logged. Details of the format are available with help=lo. This is intended to give the operator feedback that the correct version of the .rxg file is in use. Thanks to Alastair Gunn (Jodrell Bank) for suggesting this.

    2. Full logging of .rxg file non-comment lines.

      When an LO is configured with the lo command, the contents of the corresponding .rxg file are logged, but not displayed. This only occurs if this is the first time this .rxg file matched an LO being configured since the most recent opening of the current log. Each logged line starts with :rxg_file, followed by the name of the .rxg file, and then the values from a single non-comment line in the file. The lines are logged in the order from the .rxg file. This is intended to provide historical information about the values being used in FS calculations.

  11. Add hooks for local LO control to lo and lo_config commands.

    1. Hook in lo command.

      While the FS has an option for any built-in command to have a local version, having such a local overriding command can create a maintenance burden if the FS command is updated. Some commands very rarely change, but others change fairly often. The more often they change, the more maintenance burden there is. Unfortunately the lo command changes fairly often.

      To address this issue, a hook has been added to the FS version of the lo command to run antcn in a particular local mode to configure an LO when it is commanded. This is triggered with the environment variable FS_LO_ANTCN_MODE. The details of the interface are available in the Comments section show with help=lo. This may not be a suitable solution in all situations. If you have (or need) a local lo command you can continue to use it (or implement one), but it will need to be updated to get new capabilities such as new racks and logging .rxg files when they come along.

      Note
      		 This change does not currently provide a way to display LO configuration information read back from the device.

    2. Hook in lo_config command.

      The drudg program provides a means to include the calling of a lo_config command at the end of each IF setup procedure it generates. This is intended to provide stations that implement commanding the LO configuration to device(s) with a way to do it in one step for a mode as to opposed individually with lo=…​ commands. It can also be used to implement command of the LO setup for a mode instead of with the lo command to reduce (but not eliminate) the maintenance burden that is needed if a local lo command is used. See the example /usr2/fs/st.default/control/skedf.ctl file for how to trigger drudg's use of this command (also see the related skedf.ctl fix in this sub-section.

      Until now the lo_config command has been a station only command, i.e., it had to implemented as a local command. With this update, there is now a built-in command that can used for this functionality, if it is suitable. If it is not suitable, the local command can still be used or implemented.

      By default the built-in lo_config command is a no-op. However, it has a hook that can used to run antcn in a particular local mode to implement configuring the LOs. This is triggered with the environment variable FS_LO_CONFIG_ ANTCN_MODE. The details of the interface are available in the Comments section shown with help=lo_config.

  12. Fix example /usr2/fs/st.default/control.skedf.ctl (closing #81). The example sked.ctl file incorrectly identified the lo_config keyword as if_config. This has been fixed. It is recommended that you check and, if needed update your local copy in /usr2/control/skedf.ctl appropriately, including the comments.

  13. Fix ignoring antcn errors in the satellite and satoff commands. (closing #82). This bug caused errors from antcn to be ignored for only these commands. It has been fixed.

3.4. Details of drudg changes

  1. Fix crash if $HEAD is the last block in a .skd file. Fixed bug in reads.f.

  2. Fix crash if error in mask (closing #74). A particular error in the mask format intermittently excited an uninitialized variable bug. Thanks to Beppe Maccaferri (Medicina) for reporting this. He discovered it while testing with r1971.skd (which was not an experiment that included Medicina).

  3. Clean-up source.

    1. Remove references to passes, headstacks, and S2.

    2. Add the GPL to files it was missing from.

    3. Unify source between sked and the FS.