\def\pagenumbers{\footline={\hss\tenrm\folio\hss}} %\magnification=\magstephalf % 1.1 magnification \lineskip=2 truept % minimum interline clearance \parindent=0pt %\baselineskip=15 truept plus .2 truept % 3.428 lines/inch \parskip=18 truept plus 5 truept minus 2 truept % paragraph skip one line \hsize=6.2 truein % page width \vsize=9 truein % page height \font\figfont=cmr8 \font\mainfont=cmr12 \def\figa#1{\centerline{\hbox{\figfont{ #1}}}} \def\figb#1{{\leftskip=2.5 truecm\rightskip=1 truecm\noindent \figfont{\smallskip #1\smallskip}}} \settabs 3 \columns \pageno=1 \input verbatim \startverbatim %\mainfont \centerline{\bf PROGRAMMER'S GUIDE FOR PROGRAM MKBSD (Version 1.0--16/3/92).} {\bf 1. Introduction.} The program MKBSD forms part of the post-launch software for the BCS experiment on SOLAR-A. This program allows the user to select the BCS spectral data from a given BDA file containing the reformatted data for particular channels and for a particular time interval and to accumulate the spectral data as required. The data may be corrected for dead-time effects; for detector non-linearity and crystal curvature; for pointing variation; and for Germanium fluorescence and aliasing (spike) effects. The accumulated spectra are written to the BSD file in the form count rate/unit bin at the corrected bin positions. MKBSD is divided into four sub-sections : \bigskip {\parskip=0pt \parindent=40 pt\rightskip=40 pt \item{$\bullet$} a set-up section where the user specifies various parameters and options for the processing, such as BDA file name and time period of interest (subroutine QASESS); \item{$\bullet$} an accumulation control section where the decision is made as to which spectra to include within the current accumulation (subroutine CKSPEC); \item{$\bullet$} an accumulation section where the spectral data is read from the BDA data file; decompressed; degrouped (if required); any corrections applied and then accumulated together (subroutine SPECTR); \item{$\bullet$} an output section where the spectra are written to the BSD file together with header information specifying time, integration period {\it etc.} (subroutine WRDATA). } These sub-sections form the four main subroutines of MKBSD. The program may be run interactively or in batch mode from a control file. The control file can be created by running the program interactively and may be adapted from an existing control file. The interactive section of the code allows the user to check the parameters specified are sensible and display various parts of the BDA file and information on the BSD file that will be produced. {\bf 2. Programming conventions used.} We have aimed to achieve portability between the different computer hardware used by the consortium. The FORTRAN77 standard and the STARLINK software guide have been adhered to as far as possible. However : \bigskip {\parskip=0pt \parindent=40 pt\rightskip=40 pt \item{$\bullet$} INCLUDE statements have been allowed to ease changes in the BDA file format; \item{$\bullet$} duplicate routines using STRUCTUREs have been implemented for some of the BDA file read routines; \item{$\bullet$} BYTE and INTEGER*2 variables are used in some of the low-level routines handling the BDA data. } In addition, note that : \bigskip {\parskip=0pt \parindent=40 pt\rightskip=40 pt \item{(1)} Data read from the BDA data file are passed between subroutines in the program using COMMON blocks rather than STRUCTUREs. \item{(2)} Unused fields in files are explicitly blanked in case they are used at a later date. \item{(3)} Error control is kept at top level of program i.e program cannot terminate in a subroutine. If a fatal error occurs then a warning is printed and the subroutine returns with an error flag set. \item{(4)} The interaction with the user is confined to the interactive section at teh start of the program. \item{(5)} Data files required by the program for calibration tables are pointed to by alphanumeric strings which are logically attached to the files externally to the program. \item{(6)} Printed output from the program is performed through a number of low level routines allowing changes to be made to the output with minimum disturbance to the rest of the program. } {\bf 3. Miscellaneous points.} \bigskip {\parskip=0pt \parindent=40 pt\rightskip=40 pt \item{(a)} The program is designed to run on only a single BDA file. Each BDA file will contain one orbit of data. \item{(b)} The program uses decimal time stored in double precision variables (to retain sufficient accuracy i.e 100ms in 1 year) for internal format. This simplifies problem of calculating with previous internal format of days and millisecs in day. \item{(c)} The control file is an ANSI text file and will simply consist of parameters and options arranged in the order expected by MKBSD. } {\bf 4. BSD file format.} The BSD file contains spectra acccumulated from the BDA file spectra. The BSD file consists of a header section, followed by a data section, followed by pointer arrays to the data for each channel. The header section contains a pointer to the pointer arrays. The file is a fixed length (64 byte) unformatted file and opened in direct access mode. The different channel data in the BSD file are stored in the form : data for all required channels for given accumulated spectra followed by the data for subsequent accumulated spectra. Unused fields in the BSD file are blanked out. See BSD file format document for further information. \vfill\eject {\bf 5. Structure of program MKBSD.} | MKBSD -- QASESS -- PRTVNM -- PRTVAL -- RDPRMF -- QUERY -- QRYVAL -- MKFLNM -- QRYOPT -- CONCOD -- MKFLNM -- OPNFLS -- OPNFIL -- RDPNTR -- RDHDR -- RDQSIX -- RDDPHD -- RDDPSN -- SETTIM -- PRHDR -- PRQSIX -- PRDPHD -- SMSPEC -- RDRDMP -- PRRDMP -- PRTVA1 -- RDDPSN -- PRDPSN -- PRTDSN -- HELP -- CONCOD -- RDPRMF -- WRPRMF -- CKHDR -- CKRDMP -- PRTTI0 -- CKSPEC -- -- SMTOTS -- OPNFLS -- -- PRPNTR -- PRHDR -- PRQSIX -- PRDPHD -- PRDPSN -- -- PRTTIO -- CALTAB -- CKSPEC -- PRTTI1 -- RDRDMP -- PRRDMP -- -- DCGPPN -- RDDATA -- PROJPT -- SMACCS -- PRTACC -- PRTVA0 -- SPECTR -- PRTTI2 -- RDRDMP -- RDDATA -- EXPAND -- DECOMP -- PRDATA -- PRTVA2 -- DEADTM -- DSNVLS -- PRTTI3 -- PRTVA3 -- RDDPSN -- DTCORR -- DTSOLV -- PRDOSN -- CALIB -- DGROUP -- RESAMP -- ACCUM -- PROJPT -- CALCS -- SETWAV -- WRDATA -- SMTOTS -- WRHEAD | In addition to the above routines there are several utility routines. Routines which handle printout to screen : | PAUSIF, PAUSED, PRTERR, PRTLIN, PRTSTR, PRTINT, PRTINS, PRTREL, PRTRLS, PRTTIM. | Routines which handle getting information from user : | GETSTR, GETINT, GETINS, GETREL, GETRLS, GETTIM. | Routines which deal with time conversion : | INTDEC, DECINT, EXTINT, INTEXT, EXTDEC, DECEXT. | Various utility routines : | CKTIM, STRCAS, GETLUN, DELFIL, CLSFIL. | {\bf 6. Brief description of routines for MKBSD.} ACCUM Adds current set of individual spectra to accumulated spectra. CALCS Sums counts in corrected BSD spectra and finds the BSD spectrum for each channel with the peak count rate. CALIB Corrects counts in groups of bins for variation in sensitivity using calibration table. CALTAB Reads in the calibration data for non-linearity and sensitivity corrections and sets up correction tables containing positions of bin boundaries and sensitivities of each bin and sets up initial values of wavelength dispersion and offset. CKHDR Checks parameter values are reasonable by looking at the header section of the BDA file. Tries to adjust them if not. CKRDMP Loops through the road-map section of the BDA file to determine first and last road-map records and details of spectra that will be produced. CKSPEC Loops through the road-map section performing a dummy run of the spectra accumulation. Does a single spectra accumulation. Returns the start and end road-map records used in the accumulation. CKTIM Checks that the time in external format represents a valid time. CLSFIL Close file on logical unit number LUN. file. CONCOD This subroutine converts a character string code entered by the user into an integer code. DCGPPN Uses the grouping plan from the quasi-static index section to set up the number of group sets, the number of groups and bins per group in each group set for each channel. DECEXT Converts time in double precision decimal format : time in secs. since 1979.0; into external format : hrs, mins, secs, msecs, day, month, year. DECINT Converts time in into decimal format : seconds since 1979.0; into internal format : days since 1979.0, millisecs of day; DEADTM Applies a deadtime correction to the decompressed, pre-accumulated data from the BDA file. DECOMP Decompression program for Solar A BCS. Given a compressed value of counts in a bin, produce a true value of input counts. Uses a compression scheme of "constant error" designed by AF, produced by programm SCHEME CONSTANT.PRO. DELFIL Close and delete file on logical unit number LUN. DGROUP Divides counts in a group of bins in BDA spectra amongst individual bins. DSNVLS Finds the data synchronous record corresponding to the current data set and extracts various parameters. DTCORR Corrects the Encoded Events countrate for the dead time of the position encoding electronics in the Solar-A BCS. DTSOLV Solves equation Cobs = Ctrue*exp(-Ctrue*tau) , where tau = dead time, for deadtime correction routine. EXPAND Decompresses the raw BCS data for the required channels. EXTDEC Converts time in external format : hrs, mins, secs, msecs, day, month, year ; into double precision decimal format : time since 1979.0 EXTINT Converts time in external format : hrs, mins, secs, msecs, day, month, year ; into internal format : days since 1979.0, millisecs of day. GETINS Reads arbitrary number of integer values, up to a maximum of MAXVAL, entered by the user. If read successful signals with a status flag. GETINT Read an integer value entered by the user. If read successful signals with a status flag else leaves input integer value alone. GETLUN Returns an unused logical unit number for opening a file. GETREL Read a real value entered by the user. If read successfully signals with a status flag else leaves input value alone. GETRLS Reads arbitrary number of real values, up to a maximum of MAXVAL, entered by the user. If read successful signals with a status flag. GETSTR Read a string entered by the user. If read successfully signals with a status flag else leaves input string alone. GETTIM Converts character string entered by user giving a time into time in external format. HELP This subroutine provides the user with some descriptive information on the commands allowed in the query session. Called by QUERY. INTDEC Converts time in into internal format : days since 1979.0, millisecs of day; into double precision decimal format. INTEXT Converts time in internal format : days since 1979.0, millisecs of day; into external format : hrs, mins, secs, msecs, day, month, year. MKBSD Allows the user to reformat the raw BCS spectral data contained in the BDA data file into accumulated spectra. MKFLNM Makes the BDA or BSD file names up from the prefix and file ID. OPNFIL Makes the BDA or BSD file names up from the prefix and file ID, opens the file returning the logical unit number of the file and the file name. OPNFLS Routine opens the BDA file and reads the pointer, header, quasi-static index and optional data header sections. Opens the corresponding BSD file. PAUSED If in interactive mode routine waits for user input before contiuing. PAUSIF If in interactive mode and twenty lines have been printed, routine waits for user input before continuing. PRDATA Prints out some of the values contained in the BDA data section. PRDOSN Prints out results of application of deadtime correction. PRDPHD Prints out some of the values contained in the BDA optional data header section. PRDPSN Prints out some of the values contained in the BDA optional data section. PRHDR Prints out some of the values contained in the BDA header section. PROJPT Dummy routine which will eventually calculate the projection of the pointing onto the crystal axis and return the pitch yaw and roll for the current spectra data set. PRPNTR Prints out some of the values contained in the BDA pointer section. PRQSIX Prints out some of the values contained in the BDA quasi-static index section. PRRDMP Prints out summary of individual spectra using road-map record. PRTACC Prints out information about the run through the road map section for V>0. PRTDSN Prints out information on optional data section record. PRTERR Prints out standard error message giving routine NAME and error code. PRTINS Prints out character strings followed by integer values. PRTINT Prints out character strings followed by integer value. PRTLIN Prints out character string. PRTREL Prints out character strings followed by real value. PRTRLS Prints out character strings followed by real values. PRTSTR Prints out first character strings followed by the first word in the second string. PRTTI0 Prints out header for table of BSD spectra with V=0. PRTTI1 Prints out header for table produced by CKSPEC with V=1. PRTTI2 Prints out header for table produced by SPECTR with V=1. PRTTI3 Prints out headerfor table produced for DSNVLS with V=2. PRTTIM Prints out character strings followed by time. PRTVA0 Prints out table on accumulated BSD spectrum from BDA road-map section for V=0. PRTVA1 Prints out BDA spectra road-map information in listed format for V=1. PRTVA2 Prints out information in listed format about corrected BDA spectra for V=1. PRTVA3 Prints out information on optional data section values extracted for deadtime correction with V=2 in routine DNSVLS. PRTVAL Prints out current values of parameters and settings of options. PRTVNM Prints out current version number of MKBSD program. QASESS Allows the user to set up parameters and options for controlling the reformatting of the BCS BDA data file into BSD spectral data files. Opens the BDA and BSD files, prints out diagnostics and, if in interactive mode, queries user for parameters. QRYOPT Prints out current option settings and codes for changing settings. QRYVAL Prints out current values of parameters and settings of options and codes for changing settings. QUERY This subroutine is allows the user to set the values of various parameters and options and display information on the chosen data file. RDDATA Reads in the current index/data record specified by the current road-map common block. RDDPHD Reads in the parameters contained in the header section of the optional data part of the BDA file. RDDPSN Reads in the parameters contained in the optional data section of the BDA file. RDHDR Reads in the parameters contained in the header section of the BDA file. RDPNTR Reads in the parameters contained in the pointer section of the BDA file. RDPRMF This subroutine is called to read in the parameter values and option settings used by MKBSD from a control file. RDQSIX Reads in the quasi-static index section. RDRDMP Reads in the road-map record specified by RECNO. RESAMP Divides counts in a single physical bin into unit bins. SETTIM Gets times of first and last data sets in external format from header section of BDA file. SETWAV Sets wavelength offset and dispersion for accumulated spectra, optionally correcting for absolute pointing and flare offsets (not used at present). Inverts spectra for channels 1 and 2. SMACCS Prints out summary of individual accumulated BSD spectra. SMSPEC Prints out a summary of the data in the road-map section and optional data section of the BDA file. SMTOTS Prints out summary of all accumulated BSD spectra. SPECTR Reads in the individual spectra data sets from the BDA file. Decompresses them, applies any consistency checks required, corrects the spectra for dead-time, accumulates the spectra together into accumulated spectra. Applies any sensitivity correction required to the accumulated spectra and converts them to count rate against bin position. STRCAS Converts character string to lower case, left adjusts character string and returns number of characters. WRDATA Writes the housekeeping and data section for the required channels in BSD File. WRHEAD Writes the BSD file header section and an array containing pointers to the spectra data sets for each channel within the file. WRPRMF This subroutine is called to write out the parameter values and option settings used by MKBSD to a control file. \endverbatim \bye