5.1 ARCGEN

5.1.1 Overview

Program ARCGEN is the front end production program for the ULYSSES (ISPM) LAN instrument. It reads data from raw EDR tapes (Experiment Data Record - generated by JPL) and generates Archive tapes in the format specified in the ISPM LAN Archive tape definition document. ARCGEN also merges in orbit and attitude information from a data file extracted from the SEDR tape (Supplementary EDR - also generated by JPL). In addition to the Archive tape, ARCGEN also generates local files containing production information, instrument status, and synoptic data.

The program runs with a minimum of operator intervention. At the beginning of the program, the operator must specify the input and output device (or file) names for the EDR tape and Archive tape, respectively, and the EDR tape label. In addition, a supplementary output tape identifier must be specified. This identifier will be tagged on to the end of the nominal Archive tape label (ULAdddyy, where ddd is the Julian day and yy is the year of the start of data on the tape). It is used to differentiate different processing runs or EDR tape versions covering the same time interval. After this information is entered, the program proceeds without further intervention. As the program proceeds, it displays the time of the data being processed roughly once every hour of data time. On completion, the program displays a copy of the production log entry.

Example

% arcgen
Input device name (default = /dev/rmt0 ) : 
Output device name (default = /dev/rmt1 ) :
EDR tape label (16 char) >F2628B
Enter a run id ( 8 char) >A

The output tape label should be: ULA84326A 
Processing 1984/326:19:49:31
Processing 1984/326:20: 0: 7
Processing 1984/326:21: 2: 0
Processing 1984/326:22:18:35

Production Date: 85-JUL-25

---------------------------------------------------

%

To run ARCGEN, followed by STATMRG and SYNCHK (to organize the status and synoptic data bases), use the command file 'AUTO'; e.g.:
% source auto

Programming Level

Files needed to create ARCGEN are:

These files are on account dwc, directory usr1/dwc/ispm/arcsrc. The arcsrc directory is also linked onto the ISPM account for convenience, but the source can only modified from account dwc.

Files needed to run ARCGEN are:

Files created by ARCGEN are:

Routines in arcgen.f:

1. Program ARCGEN

This program first calls 'init', and then loops through a series of calls to get a lan record, check its validity, and extract status, rate, MFSA, PHA and synoptic data ('getlan', 'valid', 'stat', 'lanah', 'lanlog', 'times', 'rates', 'mfsa', 'pharc', 'syn'). When End-of-File is reached on the EDR input tape file, production is wrapped-up by 'clean' and the program stops.

Routines in archdr.f:

1. getah( archd, rt )

This routine gets a copy of the current Archive record header into the array 'archd', and then sets the record type in 'archd' to 'rt' (character*4).

2. getahl( archd, rt )

This routine is like getah except that it gets the information for the previous LAN record (used for MFSA block header).

3. updah( archd )

This routine updates archive header 'archd' with information from the current Archive record header, in the 'ending' or 'last occurrence' locations (i.e., sfdu(*,2), itime(*,2), preamb(*,4), trail(*,2), house(*,2), bfield(*,*,2), axis(*,*,2) ).

4. updahl( archd )

This routine is like updah, except that it gets the information from the previous LAN record.

5. indexah( archd )

This routine appends an Archive record index to archive header 'archd'. It is called just before writing the record to tape.

6. initah( edr )

This routine initializes the archive header. It takes information from the first EDR record read (called by 'getedr'), from the system (date and time), and from the operator (EDR tape label). The ARCGEN version number resides in this program. In addition, the instrument description file version number is encoded into the Archive header from 'instr.inc' (extracted from IDF.DAT).

7. setspn( archd, se, spin )

This routine modifies the spin start and end values in Archive header 'archd'. If 'se' = 1, the starting spin is set to 'spin'. If 'se' = 2, the ending spin is set to 'spin'. Note that the default values for start and end spin are 1 and 10 respectively.

8. lanah( lan, sfdu0 )

This routine updates the current Archive header with information from the latest lan record 'lan'. It also inserts the latest SFDU information from 'sfdu0', computes the start time and inserts the bit rate. Housekeeping and magnetic field information are also extracted from spacecraft status information embedded in the 'lan' block.

Routines in bfield.f:

1. getbf( lan, bfield )

This routine computes magnetic field information from the housekeeping information of the HED magnetometer embedded in the 'lan' array. It uses conversion coefficients from the IDF.DAT file, and generates the 'bfield' array for the Archive record header.

Routines in clean.f:

1. clean( )

This routine is called by arcgen to wrap up the production task. It outputs any partial Archive MFSA or PHA records and then calls 'puttrl' to write a trailer record. Then two file marks are written to the output Archive tape. 'putlog' is called to write the production log and 'putsyn' is called to write the last synoptic file record.

Routines in getlan.f:

1. getlan( lan, sfdu )

This routine gets the next LAN record (4 formats) from the EDR record into 'lan'. To do this it must synchronize the formats in the EDR record to the 4-format pulse. 'lan' actually contains 8 formats, including the 4 formats following the current one, which are used for validity checking. In addition, getlan returns the latest SFDU information from the EDR header in 'sfdu'. The time of the 4-format pulse 'T4F', and the see-sun time 'TSUN' (in seconds since Jan 1 1950), and the current telemetry mode 'TLMMD' (bit rate) are also computed.

2. getedr( edr )

This routine is called by 'getlan' to get the next EDR record into 'edr'. getedr also checks if the record read is a valid LAN EDR record, and skips it if not. Tape records are read with the LAN standard tape interface 'vaxmt'. After reading the first good LAN EDR record, 'initah' is called to initialize the Archive header with information from the EDR header.

3. edrchk( edr, tlmmd )

This routine is called by getedr to check that the record read is a valid LAN EDR record. It checks the Mission ID field, the Major Class field, and the Minor Class field of the EDR SFDU header to ensure it is an ISPM EDR LAN record. The telemetry mode is also checked to verify LAN data is present.

4. seqchk( edr, tlmmd )

This routine extracts the spacecraft clock and bitrate information from the EDR SFDU record header, and checks that the clock increments correctly (i.e., checks for gaps). It is called by 'getlan'.

Data in Block Data index:

1. Block Data index

This block initializes the common block in 'eindex.inc', which contains indices into a 'lan' record for housekeeping information. Indices are offsets from the start of 'lan'.

2. Block Data indexg

This block initializes the common block in 'gindex.inc', which contains indices into the FS array in the rate block for the computation of the GG array in ratblk.

3. Block Data indexl

This block initializes the common block in 'lindex.inc', which contains indices into a 'lan' record of data, sorted into arrays matching those in the Archive record. The indices are initialized to offsets into the LAN telemetry. The 'iindex' routine converts these indices into actual offsets into the 'lan' block (i.e., adds offsets due to the embedded housekeeping words).

Routines in init.f:

1. init( )

This routine calls the various initialization routines (except 'initah', which is called by 'getedr'). It calls 'iunits', 'iinstr', 'iindex', 'idecoma', and 'igamma'. It is called by arcgen.

2. iunits( )

This routine gets the input (EDR) and output (Archive) file names from the operator, with defaults specified in 'units.inc'. These file names are those passed to 'vaxmt' when doing tape I/O. Under the UCB/SSL UNIX implementation of 'vaxmt', these names can be disk files, but care must be taken in doing this to the output file since the record size is variable. The 'arcdump' program can read these disk files, but currently nothing else can.

3. iinstr( )

This routine reads the formatted data file IDF.DAT and extracts the instrument parameters such as geometric factors, etc. The format of IDF.DAT records is a1,a4,5(1x,e12.5). If the first character of a record is a '*', then the record is ignored (i.e., it is a comment). Otherwise this character is ignored. The next field contains the name of the detector that this record refers to (i.e., E1, P8, etc.). The last four fields contain information about that detector. The information contained depends on the detector. See IDF.DAT for an example. The IDF must also contain a record with name 'VERS', with the first data field containing the IDF file version number in the format n.nn.

4. iindex( )

This routine converts the LAN indices in 'lindex.inc' into indices of the 'lan' block (see 'Block Data indexl' in 'index.f' above).

5. reindx( i )

This function returns the 'lan' block index for the LAN index 'i'. It is used by 'iindex' above.

6. idecom( )

This routine initializes the 8 -> 19 bit decompression array 'decomp' in common /decom/. This array is used to decompress rate and MFSA data.

7. igamma( )

This routine calculates the values of log(E1/E2) used in the GG gamma calculation in 'rates.f' for the rateblock. The values of the energy passbands are in 'instr.inc', extracted from IDF.DAT.

Routines in lanlog.f:

1. lanlog( )

This routine records the LAN file information for the production log. The first time this routine is called, it initializes the trailer and production log routines ('initlr' and 'inilog').

2. initlr( )

This routine initializes LAN file statistics for the LAN Archive file trailer record.

3. savbps( bpscd )

This routine records the telemetry mode (bitrate) statistics. 'bpscd' is the telemetry mode of the current LAN record.

4. savgap( oldtim, newtim, bpscd )

This routine collects statistics on data gaps. It ignores data gaps shorter than one LAN record, but includes gaps caused by 'valid' rejecting whole LAN records. 'oldtim' is the start of the gap and 'newtim' is the end of the gap. 'bpscd' is the current bit rate, used to estimate the number of records missing.

5. savtyp( rt )

This routine records statistics on the output Archive record types. 'rt' is the record type code (character*4 - e.g., 'RATE').

6. puttrl( )

This routine outputs the trailer record to the LAN Archive tape.

7. inilog( )

This routine initializes the production log statistics, and opens the production log file.

8. putlog( )

This routine outputs a record to the production log (called by 'clean').

Routines in logfns.f:

See ARCLOG program description.

Routines in mfsa.f:

1. mfsa( lan )

This routine extracts MFSA data from the 'lan' block, and computes the synchronous rates from the rate block 'ratblk.inc'. When the MFSA block is full, the record is written to the Archive tape.

2. mfsachk( lan, sched )

This routine checks the data validity flags to see if there is any good MFSA data in 'lan'. It also decides if it is time to write the MFSA archive block onto tape. 'sched' is returned, and is the current MFSA schedule number.

3. mfsaput( )

This routine outputs the MFSA block to the Archive tape.

4. mfsainit( )

This routine initializes the MFSA block to zero, so missing schedules, rates, and time intervals are zero.

5. getstat( lan, sched )

This routine extracts the MFSA schedule number 'sched' from the 'lan' block status words.

6. mfsarate( lan, sched, chk )

This routine buffers up the synchronous rates extracted by 'getrata' for one 'lan' record so that they match the MFSA data. It also calls 'putrata' to put the previous 'lan' record's rate information into the MFSA block. 'sched' is the MFSA schedule number, and 'chk' indicates if the current MFSA schedule contains any valid data.

7. getrata( r8a, r4a, singa, t8a, t4a, tsa )

This routine extracts averages of rate information from the rate block 'ratblk.inc' for inclusion in the MFSA block. The dummy parameters are the returned rate information.

8. putrata( r8a, r4a, singa, t8a, t4a, tsa, sched )

This routine takes the rate averages generated by 'getrata' and buffered by 'mfsarate' and computes the synchronous averages included in the MFSA block.

9. mfsasched( lan, sched )

This routine extracts MFSA schedules from the 'lan' block. 'sched' is the schedule number.

10. getsc4( lansa, sa, tsa )

This routine extracts an MFSA schedule for a detector sectored by 4 from the 'lansa' block into the 'sa' array, and does decompression using the 'decomp' array in the 'decom' common block. It also computes the time interval array 'tsa'.

11. getsc8( lansa, sa, tsa )

This routine is like 'getsc4' above, except that it extracts schedules for detectors sectored by 8.

Routines in pha.f:

1. pharc( lan )

This routine extracts Pulse Height Events from the 'lan' block into PHARC blocks, and writes the output to the Archive tape. It also maintains synchronous averages of selected rate data.

2. putevt( lan, c, d, p, sect, spin, sttime, code )

This routine checks event 'c','d','p', and if non-zero, adds it to the current PHARC block.

3. inipha( )

This routine resets the PHARC block to zero.

4. putpha( )

This routine writes out the PHARC block to the Archive tape. Before writing, it normalizes the synchronous rates.

Routines in rates.f:

1. rates( lan )

This routine extracts rates from the 'lan' block to generate a RATEBLK Archive record.

2. getrh( rechd )

This routine gets the pitch angles and orientations included in the RATEBLK Archive record header.

3. putrat( buf )

This routine writes the rate block 'buf' to the Archive tape.

4. getrat( lan, r8, r4, rs, t8, t4, ts )

This routine extracts and decompresses the rates 'r8', 'r4' and spin averaged rates 'rs' from the 'lan' block. It also integrates the sampling intervals 't8', 't4', 'ts'.

5. getflx( rs, fs, fo )

This routine computes the fluxes 'fs' and 'fo' from the spin averaged rates 'rs'.

6. getgam( fs, gg )

This routine computes the spectral exponents, 'gg' from the spin-averaged fluxes 'fs'.

Routines in stat.f:

1. stat( lan )

This routine controls the instrument status log. It checks the status words in the 'lan' block and writes a status block if there is any significant change, or if more than 16384 seconds (about 4 hours) has passed.

2. putstat( )

This routine writes the current status information to the status file.

Routines in syn.f:

1. syn( lan )

This routine calculates rate averages, using the information in the rate block 'rateblk.inc' for the synoptic data file.

2. inisyn( scclk )

This routine initializes the synoptic data values. 'scclk' is the initial spacecraft clock value.

3. putsyn( )

This routine writes a synoptic data file record.

Routines in synfns.f:

See ARCSYN program description.

Routines in timcon.f:

1. timcon( itime, second )

This routine converts 'second', in seconds since 1950, into the LAN Archive 'itime' array format (year,day,hour,minute,second - NOT second*100).

2. sec1950( itime )

This routine does the inverse of 'timcon', returning the value of 'second'.

Routines in times.f:

1. times( lan )

This routine computes the start time of the first spin and the time intervals of the sectors in the block 'lan', accounting for skipped spins, short sectors, etc.

Routines in valid.f:

1. valid( lan )

This routine checks the validity of data in 'lan' block. It checks both the Data Presence Indicators (DPI) in the EDR SFDU header and status information in the 'lan' block status and trailer words. The strategy for missing validity check words is that if the data was previously good, it is assumed to continue good, otherwise it is assumed to continue bad.

2. dpival( lan )

This routine checks the DPIs for the 'lan' block. MFSA data is thrown out in units of one spectra, and rate data is thrown out in units of one spin pair.

3. lanval( lan )

This routine checks the validity of data in 'lan' block on the basis of status and trailer information. Validity is based on the 'Validity Checks of LAN DATA Stream' note, LAN-082-85 by R. E. Gold.

4. pwrchk( pstat )

This routine checks the power status of subsystems and sets the appropriate detector validity flags (see LAN-082-85).

5. dpichk( index )

This routine returns the validity of the data at 'lan' offset 'index' based on the DPI flags.

6. getmsk( frm0, frm1, dpimsk )

This routine returns a mask 'dpimsk' to use with DPI words to check if data in the range 'frm0' to 'frm1' (frame numbers) is OK.

Routines in util.f:

Routines marked with a '*' are system dependent.

1. copy( dest, src, n )

This routine copies 'n' 4-byte quantities (I*4 or R*4 or 2 I*2's or 4 characters) from 'src' to 'dest'.

2. prompt( pr )

This routine prints out prompt 'pr' to the standard output unit without an end-of-line.

3. msg( m)

This routine prints out message 'm' to the standard output unit.

4.* gettim( yr, mo, dy, hr, mn, sc )

This routine gets the current time from the system.

5.* location( arg )

This routine returns the address of argument 'arg'.

6.* pfioerr( msg )

This routine prints 'msg' followed by a description of the latest fortran I/O error to the standard output device (console).

7. ibm2( c )

This routine returns a 2 byte integer quantity (I*2) from character array 'c' written by an IBM 4341 (i.e., the ISPM EDR tape) - it swaps the bytes.

8. ibm4( c )

This routine is like 'ibm2' above, but for 4 byte quantities (I*4).

9. fibm( c )

This routine converts IBM 4341 floating point numbers to the local floating point representation. The IBM F.P. number is in character array starting at 'c'.

10.* iand( i, j )

This function returns the bit-wise logical and of i and j (I*4).

11.* ior( i, j )

This function returns the bit-wise logical or of i and j (I*4).

12.* inot( i )

This function returns the bit-wise logical complement of i (I*4).

13.* ixor( i, j )

This function returns the bit-wise logical exclusive or of i and j (I*4).

14.* ilshft( w, n )

This function returns the value of 'w' shifted left 'n' times (I*4).

15.* irshft( w, n )

This function returns the value of 'w' shifted right 'n' times (I*4).

Routines in mtio:

1. vaxmt( unit, function, density, buf, nbytein, nbyteout, ierr )

This is the UCB/SSL UNIX version of the ISPM-LAN standard tape I/O routine. 'unit' is the character*n name of the device, 'function' is the tape function code (read, write, rewind, etc.; see below), 'density' is the tape density (not used on UNIX version - density is selected either manually on the tape drive or automatically by the choice of device name - see UNIX manual mtio(4). 'buf' is the array read into/ write from. 'nbytein' is the requested transfer size. 'nbyteout' is the actual transfer size returned. 'ierr' is the error code, currently -1 for an error, 0 for OK. To get a description of the error on the standard output device (console) use 'perr'. On reading an end-of-file, nbyteout returns 0.

Function Codes:

0 - Rewind and unload (close).
1 - Read up to 'nbytein' bytes into 'buf' from tape
2 - Write 'nbytein' bytes from 'buf' onto tape
3 - Write EOF to tape
4 - Skip 'nbytein' records (+=forward, -=backward)
5 - Skip 'nbytein' files " "
6 - No operation
7 - Rewind

2. ptioerr( msg )

This routine prints 'msg' followed by a description of the latest error condition onto the standard output device (console). Used for 'vaxmt' error decoding.

Next: A5.2 ARCDUMP

Return to Appendix 5 Table of Contents Page

Return to HISCALE List of Appendices