5.6 The fotlib library

Use the subject list in the previous page, or the quick alphabetic index here below to locate the routine of interest.

• add_end

  Library	fotlib	Fortran code
  Calling sequence	CALL ADD_END(ipass)
  Arguments	INTEGER	IPASS

  Category: specific of fotfile program
  This routine adds to an external shell script file the commands necessary to run the next (IPASS-th, 1,2 or 3) pass of fotfile.

• add_file

  Library	fotlib	Fortran code
  Calling sequence	CALL ADD_FILE(file,blksize,recl,type)
  Arguments	CHARACTER*(*)	FILE
  	INTEGER	BLKSIZE, RECL
  	CHARACTER*3	TYPE ('ASC'|'BIN')

  Category: specific of fotfile program
  This routine adds to an external shell script file the commands necessary to read from tape a file called FILE unblocking it from tape block size BLKSIZE to disk record length RECL according to the rules for ASCII or binary decoding as specified by TYPE.
  The system (and site) dependent template commands are read from a programming support file located in the local directory and edited replacing the tokens with the subroutine arguments, using edit_cmd

• add_init

  Library	fotlib	Fortran code
  Calling sequence	CALL ADD_INIT

  Category: specific of fotfile program
  This routine adds to an external shell script file the commands necessary to begin the operations.

• add_rew_tape

  Library	fotlib	Fortran code
  Calling sequence	CALL ADD_REW_TAPE

  Category: specific of fotfile program
  This routine adds to an external shell script file the command necessary to rewind the tape. The system (and site) dependent template command is read from a programming support file located in the local directory and edited replacing the tokens with the tape drive name (present in a COMMON block) using edit_cmd

• add_skip_tape

  Library	fotlib	Fortran code
  Calling sequence	CALL ADD_SKIP_TAPE(N)
  Arguments	INTEGER	N

  Category: specific of fotfile program
  This routine adds to an external shell script file the command necessary to skip forward N tape files. The system (and site) dependent template command is read from a programming support file located in the local directory and edited replacing the tokens with the routine argument using edit_cmd

  ---

• check_packet

  Library	fotlib	Fortran code
  Calling sequence	CALL CHECK_PACKET(PACKET,DATATYPE,N)
  Arguments	CHARACTER*(*)	PACKET
  	CHARACTER	DATATYPE ('I'|'S'|'P'|'T'|'HK')
  	INTEGER	N

  Returns the number N of packet families listed in the instrument directory and eligible for the requested accumulation DATATYPE (where the codes are for Images, Spectra, Photon files, Time profiles or HK time profiles). The PACKET argument is unused, included for compatibility with sax_which_data

  ---

• correct

  Library	fotlib	Fortran code
  Calling sequence	CALL CORRECT

  A case statement calling the appropriate event correction routine for MECS, LECS, PDS or HPGSPC.

  ---

• edit_cmd

  Library	fotlib	Fortran code
  Calling sequence	CALL EDIT_CMD(STRING,OLD,NEW)
  Arguments	CHARACTER*(*)	STRING
  	CHARACTER*(*)	OLD,NEW

  A general STRING editing routine which replaces the first occurrence of a string token OLD with the string value NEW.
  Used in particular by tape command generation routines for the fotfile program.

  ---

• exposure_b1s1

  Library	fotlib	Fortran code
  Calling sequence	CALL EXPOSURE_B1S1(ICOUNTER, ISTIME,ITIMSIZ, RECORD,CONVERT, PREVIOUS_TIMEHI, ENDWINDOW,ENDACCUM, NEWOBS,TCYCLE)
  Arguments	undocumented

  A service routine called by sax_acc_b1s1_y to update the contribution to the live exposure time of the current packet (the value is stored in TIMECOMMON). See code for further details.

• exposure_b1s3

  Library	fotlib	Fortran code
  Calling sequence	CALL EXPOSURE_B1S3(ICOUNTER, ISTIME,ITIMSIZ, RECORD,CONVERT, PREVIOUS_TIMEHI,ENDWINDOW,ENDACCUM, NEWOBS,TCYCLE, recycled)
  Arguments	undocumented

  A service routine called by sax_acc_b1s3_y to update the contribution to the live exposure time of the current packet (the value is stored in TIMECOMMON) with the same logics of the previous routine. See code for further details.

  ---

• get_start_end

  Library	fotlib	Fortran code
  Calling sequence	CALL GET_START_END(TMIN,TMAX)
  Arguments	DOUBLE PRECISION	TMIN,TMAX

  Category: accumulation support
  This routine returns the default start and end times for the accumulation, i.e. the start time of the first observation and the end time of the last observation in the current chain (as defined in the XAS environment), read from the instrument directory.
  TMIN,TMAX are in seconds (or with the resolution specified by the time constant setup)
  Side effects: information about start and end times are also stored in the OPCOMMON and TIMECOMMON blocks.

  ---

• init_correct

  Library	fotlib	Fortran code
  Calling sequence	CALL INIT_CORRECT(STUFF)
  Arguments	CHARACTER*(*)	STUFF(*)

  Essentially a case statement calling the appropriate event correction initialization routine for MECS, LECS, PDS or HPGSPC, in the case the environment requires event correction.
  The array STUFF lists the names of all event quantities which are involved in the correction.

  ---

• instr_keywords

  Library	fotlib	Fortran code
  Calling sequence	CALL INSTR_KEYWORDS(PRODUCT)
  Arguments	CHARACTER	PRODUCT ('I'|'S'|'P'|'T'|'H'|'M')

  A case statement calling the appropriate routine which adds instrument specific header keywords for MECS, LECS, PDS or HPGSPC. The PRODUCT code is used only by the PDS call, which has different sets of keywords for Images, Spectra, Photon files, Time profiles, HK time profiles or Matrices.

  ---

• lintomm

  Library	fotlib	Fortran code
  Calling sequence	CALL LINTOMM(X,Y)
  Arguments	DOUBLE PRECISION	X,Y

  Category: attitude
  Converts in place the coordinates X,Y from linearized pixels to mm on the focal plane. Although the routine is potentially general, it is implemented only for MECS since it needs to load the current pixel size.

• mmtopix

  Library	fotlib	Fortran code
  Calling sequence	CALL MMTOPIX(X,Y)
  Arguments	DOUBLE PRECISION	X,Y

  Category: attitude
  Converts in place the coordinates X,Y from mm on the focal plane to linearized pixels. Although the routine is potentially general, it is implemented only for MECS since it needs to load the current pixel size.

  ---

• rearrange_instrec

  Library	fotlib	Fortran code
  Calling sequence	CALL REARRANGE_INSTREC(INSTREC)
  Arguments	CHARACTER*133	INSTREC

  A service routine (at present used only by get_start_end and pds_keywords) to reformat an instrument directory record enclosing hex-coded values in quotes, so that it can be read with list-directed i/o.

  ---

• sax_acc_b1sn_x

  The sax_acc_b1sn_x family of routines are the packet handlers for direct mode telemetry packets (basic type 1, secondary type n). The x code equal to y indicates packets with fields reformatted to span always an integer number of bytes (as are all FOT telemetry packets), while an x code equal to i indicates fields which can use any number of bits (not necessarily multiple of 8), which was the case of raw telemetry used during ground calibrations. The latter routines are not publicly distributed (but replaced with "return end" routines) and not documented.

  All these routines have a single argument, the name of an INCREMENT_ROUTINE which must be called to process a single event (or packet, or logical portion thereof) in a way specified by each accumulation program (i.e. such routine is in the main program source file and not a library routine).

  These routines take care of all byte swapping (as dictated by the telemetry description files and the characteristics of the current operating system), of calling event corrections if required, of advancing from the telemetry file of one observation to the next in the chain, and handle time windows.

• sax_acc_b1s1_i

  Library	fotlib	Fortran code
  Calling sequence	SAX_ACC_B1S1_I(INCREMENT_ROUTINE)

  Bit (ground calibration raw data ) version of the next routine.

• sax_acc_b1s1_y

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B1S1_Y(INCREMENT_ROUTINE)
  Arguments	EXTERNAL	INCREMENT_ROUTINE

  This routine deals with basic type 1, secondary type 1 i.e. the MECS, PDS and HPGSPC direct mode packets. It computes the packet exposure time via exposure_b1s1 and decodes the events calling the INCREMENT_ROUTINE once per event.

• sax_acc_b1s2_i

  Library	fotlib	Fortran code
  Calling sequence	SAX_ACC_B1S2_I(INCREMENT_ROUTINE)

  Bit (dummy) version of the next routine.

• sax_acc_b1s2_y

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B1S2_Y(INCREMENT_ROUTINE)

  Intended to deal with basic type 1, secondary type 2 i.e. the WFC direct mode packets, is unfinished and untested.

• sax_acc_b1s3_y

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B1S3_Y(INCREMENT_ROUTINE)

  This routine deals with basic type 1, secondary type 3 i.e. the LECS direct mode packets. It includes code for correcting some of the known errors in such packet times (either present ab origine or introduced at FOT production level). It computes the packet exposure time via exposure_b1s3 and decodes the events calling the INCREMENT_ROUTINE once per event.

• sax_acc_b2s1_y

  The sax_acc_b2sn_x family of routines are the packet handlers for indirect mode telemetry packets (basic type 2, secondary type n). These routines are structured similarly to the sax_acc_b1sn_x ones.

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B2S1_Y(INCREMENT_ROUTINE)

  This routine deals with basic type 2, secondary type 1 i.e. the MECS, PDS and HPGSPC indirect mode packets. Such packet include one or more spectra : the INCREMENT_ROUTINE is called once per spectrum.
  These routines have been poorly tested since indirect packets are hardly used.

• sax_acc_b3s1

  The sax_acc_b3sn_x family of routines are the packet handlers for HouseKeeping mode telemetry packets (basic type 3, secondary type n). These routines are structured similarly to the sax_acc_b1sn_x ones.

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B3S1(INCREMENT_ROUTINE)

  Unused for flight data. Deals with ground data (Laben Block Transfer Bus instrument HK).

• sax_acc_b3s2

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B3S2(INCREMENT_ROUTINE)

  Unused for flight data. Deals with ground data (Laben/Alenia Interrrogation/Response Bus instrument and spacecraft HK).

• sax_acc_b3s3

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B3S3(INCREMENT_ROUTINE)

  This routine deals with basic type 2, secondary type 3 i.e. the MECS, PDS and HPGSPC ENGineering mode packets (containing ratemeters). It calls the INCREMENT_ROUTINE once per ratemeter sample.

• sax_acc_b3s4

  Library	fotlib	Fortran code
  Calling sequence	SAX_ACC_B3S4(INCREMENT_ROUTINE)

  This routine deals with basic type 2, secondary type 4 i.e. the MECS, PDS and HPGSPC HKD mode packets (containing instrument HK parameters from Virtual Channel 1). It calls the INCREMENT_ROUTINE once per parameter sample.

• sax_acc_b3s5

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B3S5(INCREMENT_ROUTINE)

  This routine deals with basic type 2, secondary type 5 i.e. spacecraft HKD mode packets (containing spacecraft HK parameters). It calls the INCREMENT_ROUTINE once per parameter sample.

• sax_acc_b3s6

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_B3S6(INCREMENT_ROUTINE)

  This routine deals with basic type 2, secondary type 6 i.e. pseudo-spacecraft ASCII data, namely the attitude and ephemeris files. It calls the INCREMENT_ROUTINE once per attitude or ephemeris record.
  An internal hidden routine reformats "new" attitude records (which are not compliant with the original ICD) so that they can be read with list-directed i/o as old were.

  ---

• sax_acc_bt_1

  The family of sax_acc_bt_j are trivial dispatchers handling a request for packets of basic type j and calling the appropriate "secondary type" routine sax_acc_bjsn_x. They all share a similar calling sequence

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_BT_1(IST,UNITS,INCREMENT_ROUTINE)

  is the dispatcher for direct mode data (basic type 1).

• sax_acc_bt_2

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_BT_2(IST,UNITS,INCREMENT_ROUTINE)

  is the dispatcher for indirect mode data (basic type 2).

• sax_acc_bt_3

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_BT_3(IST,UNITS,INCREMENT_ROUTINE)
  Arguments	INTEGER	IST
  	CHARACTER*(*)	UNITS ('BYTES'|'BITS')
  	EXTERNAL	INCREMENT_ROUTINE

  is the dispatcher for HK mode data (basic type 3).

  The secondary type IST and the unit for data UNITS are used to branch to the appropriate sax_acc_bjsn_x routine, to which the name of the INCREMENT_ROUTINE is passed straight on.

  ---

• sax_acc_hkrange

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_HKRANGE(NDIMENS, NFORMAT, XSTUFF, STUFF, PACKET)
  Arguments	mostly unused, included for analogy with sax_acc_range

  Category: accumulation support
  Handles the range dialogue for HK accumulations : in practice just asks and sets the start and end times and the binning time (multiple of HK sampling time) proposing appropriate defaults.

  ---

• sax_acc_loop

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_LOOP(INCREMENT_ROUTINE)
  Arguments	EXTERNAL	INCREMENT_ROUTINE

  This routine includes the entire accumulation loop on all data packets in all observations of the observation chain. In fact this routine does nothing more than retrieving from the packetcap the basic information about the current selected type of telemetry packet, and dispatching the appropriate basic type sax_acc_bt_i dispatcher routine, which in turn calls the appropriate sax_acc_bjsn_x routine (to which the name of the INCREMENT_ROUTINE is passed straight on). It is in the sax_acc_bjsn_x routine that all loops are unrolled !

  ---

• sax_acc_open_sc_tlm

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_OPEN_SC_TLM(LU,PACKET)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	PACKET

  Similar to the next routine, but opens spacecraft telemetry files (whose naming convention is slightly different, and may include ASCII files).

• sax_acc_open_tlm

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_OPEN_TLM(LU,PACKET)
  Arguments	INTEGER	LU
  	CHARACTER*(*)	PACKET

  Opens on logical unit LU the first telemetry file of the observation chain which is of type PACKET (resolving internally the file name).

  ---

• sax_acc_other_range

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_OTHER_RANGE(NDIMENS ,NFORMAT, XSTUFF, STUFF)
  Arguments	INTEGER	NDIMENS
  	INTEGER	NFORMAT
  	CHARACTER*(*)	XSTUFF(*),STUFF(*)

  Category: accumulation support
  Handles the range dialogue for uninteresting quantities in accumulations. The arguments are as for the corresponding call to sax_acc_range, which deals instead with interesting quantities. Essentially this routine constructs adequate defaults for the start and end value of each quantity (values out of range cause data rejection), and asks the user to confirm or change them (directly for all parameters except times, which are processed through asktime).

  ---

• sax_acc_preload

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_PRELOAD(NDIMENS, NFORMAT, XSTUFF, STUFF)
  Arguments	INTEGER	NDIMENS
  	INTEGER	NFORMAT
  	CHARACTER*(*)	XSTUFF(*)
  	CHARACTER*(*)	STUFF(*)

  Category: accumulation support
  This routine retrieves from the packetcap of the current telemetry packet the basic information about each of the data quantities present in the file, inclusive of their names STUFF. The arguments are those listed for sax_acc_range, except that this call is the one which loads the values in STUFF

  ---

• sax_acc_range

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_ACC_RANGE(NDIMENS, NFORMAT, XSTUFF, STUFF)
  Arguments	INTEGER	NDIMENS
  	INTEGER	NFORMAT
  	CHARACTER*(*)	XSTUFF(*)
  	CHARACTER*(*)	STUFF(*)

  Category: accumulation support
  Handles the range dialogue for interesting quantities in accumulations. Interesting quantities are those which go on the axes of the output data file (e.g. X and Y for an image, energy for a spectrum, time for a time profile or potentially any quantity for a photon file).

  NDIMENS must be set to 1 for 1-d output data files (histograms or time profiles), 2 for 2-d images and 0 for photon files.
  NFORMAT is a reserved value, which must be set to 0 for photon files or 3 for time profiles (with the exception of the latter, use the same value of NDIMENS for convenience).
  XSTUFF is an array of the names of the NDIMENS quantities considered as interesting (i.e. whatever goes on the X axis of an histogram or on the XY axes of an image)
  STUFF is an array of the names of all quantities and is used mainly for photon files. On return XSTUFF will be modified to contain the quantities accepted as interesting.
  In all cases see also sax_acc_preload and sax_acc_select for the (X)STUFF arrays.

  Essentially this routine constructs adequate defaults for the start and end value and the binning of each quantity, and asks the user to confirm or change them (directly for all parameters except times, which are processed through asktime and askbin). In the case the accumulation is that of a photon file, instead of the binning the user is asked whether the quantity has to be included in the output or not.
  The ranges may be used both for data acceptance (values out of range cause data rejection) and to dimension the size of the output data file.

  ---

• sax_acc_select

  Library	fotlib	Fortran code
  Calling sequence
  Arguments	INTEGER	NDIMENS
  	INTEGER	NFORMAT
  	CHARACTER*(*)	XSTUFF(*)
  	CHARACTER*(*)	STUFF(*)
  	INTEGER	IERR

  Category: accumulation support
  This routine selects (among the quantities listed in STUFF and preset by sax_acc_preload) the NDIMENS interesting ones, asking the user (except for time profiles, where the 'TIME' quantity is used and for photon files where this routine is not called). Their names is returned in XSTUFF.
  The arguments are those listed for sax_acc_range, plus IERR which returns a non-zero value in case of errors.

  ---

• sax_df_keywords

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_DF_KEYWORDS

  This routine writes into the header of the XAS file the standard keywords used for SAX specific accumulations, i.e. the satellite and instrument identification, and the observer and target identification (taken from tape directory). The observer name can be overridden (e.g. by the current user full name or another name) if so requested in the XAS environment.

  ---

• sax_open_dir

  Library	fotlib	Fortran code
  Calling sequence	CALL AX_OPEN_DIR(LU,NOBS,NAME)
  Arguments	INTEGER	LU
  	INTEGER	NOBS
  	CHARACTER*(*)	NAME

  This routine opens the observation directory file for observation NOBS on the logical unit LU (automatically selected), returning also its file NAME

  ---

• sax_pcf_load

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_PCF_LOAD(HKNAME)
  Arguments	CHARACTER*(*)	HKNAME

  This routine loads in memory the PCF entry for HK parameter HKNAME. The PCF (Parameter Characteristics File) is an instrument support file listing the characteristics of all HK parameters. The routine selects the current instrument PCF, or, when appropriate, the spacecraft PCF.

  ---

• sax_pcf_lookup

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_PCF_LOOKUP(FIELD,TYPE,IVAL,STRVAL,FOUND)
  Arguments	CHARACTER*(*)	FIELD
  	INTEGER	TYPE
  	INTEGER	IVAL
  	CHARACTER*(*)	STRVAL
  	LOGICAL	FOUND

  Similar to pktcap_lookup, but looks up the characteristics named FIELD of the HK parameter whose PCF entry was loaded in memory by sax_pcf_load

  ---

• sax_pktcap_load

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_PKTCAP_LOAD(PACKET)
  Arguments	CHARACTER*(*)	PACKET

  This routine loads in memory the packetcap entry for the named telemetry PACKET. The routine builds the appropriate packetcap file name and locates it, then uses pktcap_load to do the actual job.

  ---

• sax_which_data

  Library	fotlib	Fortran code
  Calling sequence	CALL SAX_WHICH_DATA(PACKET,DATATYPE,N)
  Arguments	CHARACTER*(*)	PACKET
  	CHARACTER	DATATYPE ('I'|'S'|'P'|'T'|'HK')
  	INTEGER	N

  As in check_packet, it returns the number N of packet families listed in the instrument directory and eligible for the requested accumulation DATATYPE (where the codes are for Images, Spectra, Photon files, Time profiles or HK time profiles). In addition it also returns the PACKET name selected for accumulation (this is automatic if N=1, otherwise the user is prompted for selection among a list), or a blank string if no packets available (N=0)

  ---

• tapechar

  Library	fotlib	Fortran code
  Calling sequence	CALL TAPECHAR

  Category: specific of fotfile program
  Loads the system (and site) dependent template tape commands (to be later used by tape command generation routines) from a programming support file located in the local directory.

  ---

• timebin_b1s1

  Library	fotlib	Fortran code
  Calling sequence	CALL TIMEBIN_B1S1(COVERAGE, START, END, SIZE)
  Arguments	DOUBLE PRECISION	COVERAGE
  	DOUBLE PRECISION	START, END
  	DOUBLE PRECISION	SIZE

  Computes the live COVERAGE (exposure time) of a time bin of given STARTD and ENDtimes and SIZE. Intended to be called by time profile INCREMENT_ROUTINEs called by sax_acc_b1s1_y (which fills the relevant COMMON block with appropriate information).

  ---

• unlintomm

  Library	fotlib	Fortran code
  Calling sequence	CALL UNLINTOMM(X,Y)
  Arguments	DOUBLE PRECISION	X,Y

  Category: attitude
  Converts in place the coordinates X,Y from unlinearized pixels to mm on the focal plane. Although the routine is potentially general, it is implemented only for MECS (and contains MECS specific imbedded code) since it needs to load the linearization coefficients and perform the linearization.

[Previous][Next] [Up][Down]