Portable Figaro 5.1 is not intended as a programming environment. It is not recommended to write software that calls the Figaro object libraries. You should use the Starlink and ADAM facilities instead, namely the NDF data access subroutine library and the ADAM parameter system library.
Also consult Section G.1 on changes between the VMS and Unix versions. The “Figaro Programmers’ Guide” of January 1991 is still largely valid, apart from section 12.
However, there exists a large body of code—in a handful of released software items as well as user-written private applications—that relies on calling Figaro subroutines. For this reason the compiled object libraries are included in the release of Figaro.
Let us assume that you have two private applications ‘myapp1’ and ‘myapp2’ that you want to port from VAX/VMS Figaro to Portable Figaro. As you are aware, each application consists of the Fortran source code ‘myapp1.f’ and the interface source code ‘myapp1.con’. The Fortran code needs virtually no change, but the interface must be completely re-written. You can in the first instance do an automatic conversion of the interface, but this is only possible on VAX/VMS:
Now take the two source files per application—‘myapp1.f’ and ‘myapp1.ifl’ to your Unix machine. Both are ASCII files.
In the Fortran code, you have to change any include statements. The include files should be specified only by their file name stem, without path or name extension. And they should be specified in upper case. The most common include statement then becomes
The interface file ‘myapp1.ifl’ can probably be left alone. However, if the application reads or writes what used to be Figaro user variables, then these need entries in the interface file. For a read-only variable called XXXX use this entry:
and for a write-only variable use
It is possible within one application to read through the prompt path with e.g. ‘par_rdary’ and later write into the global association with ‘var_setary’.
More elaborate schemes may prove difficult.
If you are not able to do an automatic conversion of the interface on a VMS machine, then you will have to edit your ‘myapp1.con’ into a suitable ‘myapp1.ifl’. Use the interface files of actual Figaro applications for guidance, and consult the documentation on these interface files.
If you are planning to link your application with the original AAO Figaro DSA and DTA data access libraries then the parameters used by ‘dsa_input’, ‘dsa_output’ etc. should have type ‘_CHAR’ or ‘LITERAL’, just like any parameter obtained with ‘par_rdchar’. Alternatively, if you are planning to use the equivalent Portable Figaro FDA library, then the parameters used to access data should have type ‘NDF’. (See Appendices G.1.7 and G.1.8 for details of FDA, DSA and DTA.)
It is recommended to combine all your private applications into a single monolith, in the same way that all Figaro applications are in fact in three monolithic executables. For this you need an additional Fortran source, the monolith routine. If you call your collection of applications ‘mypack’, then you would need a Fortran source ‘mypack.f’ modelled on ‘/star/figaro/figaro1.f’. You have to change the subroutine statement so that the module is called ‘mypack’ and not ‘figaro1’. And you have to change the big if-else-if block where the applications are called, so that your applications are called when their name is detected as the command.
Now you can go about compiling the Fortran code. In order for the include statements to work, you need a symbolic link from the actual include file to the one used in the source code. Figaro’s public include file is in /star/figaro, and has a lower-case name.
Next you can link your three new object files with the Figaro and Starlink libraries. Be sure that ‘mypack.o’ comes first.
‘figaro_link’ links your programs with the Portable Figaro FDA data access library. If you need to link with the original AAO DSA and DTA libraries instead then make your own copy of file ‘/star/sources/figaro/figaro_link’ and amend it accordingly.
On Solaris, currently, you also have to add an option -lucb. Be aware that in the command the
‘quotes’ are not quotes (’), but back-quotes (‘). After linking you should be left with an executable
called ‘mypack’.
If you try to run this executable you will only get an error message. But then, you want to run your two applications, not the monolith as such. In order to run your applications from the Unix shell what you need are symbolic links from the monolith to each application name:
Now you can try to run either application under its name. If the application’s interface file is in the same directory, that will even work. Otherwise you get another error message. You can use the source interface files ‘myapp1.ifl’, but it is better to compile them into binary form:
This gives you files ‘myapp1.ifc’ etc. All you need in your executable system is in one directory:
The source code (.f and .ifl) can be moved somewhere else, and the object files (.o) can be removed. You can rename the Fortran code to have file names ending in ‘.f’, as is common on Unix systems. Figaro uses ‘.for’ due to an international agreement, there is no rational reason for this.
The extra bit that Figaro does when you give the ‘figaro’ command is to define an alias for each application.
You can also extend your monolith so that you can run it from ICL instead of the Unix shell. For this you need to concatenate all your application interfaces:
You can compile this as well with ‘compifl’ and place the interface in the same directory as the monolith. In ICL you will have to define the commands in the same way as the Figaro startup script does:
There is little support for Figaro as a programming environment. In rare cases you may find that your applications call routines that have not been ported from VMS to Unix. The Figaro object libraries exist to serve Figaro applications, they do not pretend to be complete software items in their own right. (You may be lucky and the ‘missing’ routine has just been renamed.)
That is why you are encouraged to write new software using Starlink libraries, which are designed and supported as software items independent from specific applications.