/* * Copyright (C) 1998 by Southwest Research Institute (SwRI) * * All rights reserved under U.S. Copyright Law and International Conventions. * * The development of this Software was supported by contracts NAG5-3148, * NAG5-6855, NAS8-36840, NAG5-2323, and NAG5-7043 issued on behalf of * the United States Government by its National Aeronautics and Space * Administration. Southwest Research Institute grants to the Government, * and others acting on its behalf, a paid-up nonexclusive, irrevocable, * worldwide license to reproduce, prepare derivative works, and perform * publicly and display publicly, by or on behalf of the Government. * Other than those rights granted to the United States Government, no part * of this Software may be reproduced in any form or by any means, electronic * or mechanical, including photocopying, without permission in writing from * Southwest Research Institute. All inquiries should be addressed to: * * Director of Contracts * Southwest Research Institute * P. O. Drawer 28510 * San Antonio, Texas 78228-0510 * * * Use of this Software is governed by the terms of the end user license * agreement, if any, which accompanies or is included with the Software * (the "License Agreement"). An end user will be unable to install any * Software that is accompanied by or includes a License Agreement, unless * the end user first agrees to the terms of the License Agreement. Except * as set forth in the applicable License Agreement, any further copying, * reproduction or distribution of this Software is expressly prohibited. * Installation assistance, product support and maintenance, if any, of the * Software is available from SwRI and/or the Third Party Providers, as the * case may be. * * Disclaimer of Warranty * * SOFTWARE IS WARRANTED, IF AT ALL, IN ACCORDANCE WITH THESE TERMS OF THE * LICENSE AGREEMENT. UNLESS OTHERWISE EXPLICITLY STATED, THIS SOFTWARE IS * PROVIDED "AS IS", IS EXPERIMENTAL, AND IS FOR NON-COMMERCIAL USE ONLY, * AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT * SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. * * Limitation of Liability * * SwRI SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED AS A RESULT OF USING, * MODIFYING, CONTRIBUTING, COPYING, DISTRIBUTING, OR DOWNLOADING THIS * SOFTWARE. IN NO EVENT SHALL SwRI BE LIABLE FOR ANY INDIRECT, PUNITIVE, * SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGE (INCLUDING LOSS OF BUSINESS, * REVENUE, PROFITS, USE, DATA OR OTHER ECONOMIC ADVANTAGE) HOWEVER IT ARISES, * WHETHER FOR BREACH OF IN TORT, EVEN IF SwRI HAS BEEN PREVIOUSLY ADVISED OF * THE POSSIBILITY OF SUCH DAMAGE. YOU HAVE SOLE RESPONSIBILITY FOR ADEQUATE * PROTECTION AND BACKUP OF DATA AND/OR EQUIPMENT USED IN CONNECTION WITH THE * SOFTWARE AND WILL NOT MAKE A CLAIM AGAINST SwRI FOR LOST DATA, RE-RUN TIME, * INACCURATE OUTPUT, WORK DELAYS OR LOST PROFITS RESULTING FROM THE USE OF * THIS SOFTWARE. YOU AGREE TO HOLD SwRI HARMLESS FROM, AND YOU COVENANT NOT * TO SUE SwRI FOR, ANY CLAIMS BASED ON USING THE SOFTWARE. * * Local Laws: Export Control * * You acknowledge and agree this Software is subject to the U.S. Export * Administration Laws and Regulations. Diversion of such Software contrary * to U.S. law is prohibited. You agree that none of the Software, nor any * direct product therefrom, is being or will be acquired for, shipped, * transferred, or reexported, directly or indirectly, to proscribed or * embargoed countries or their nationals, nor be used for nuclear activities, * chemical biological weapons, or missile projects unless authorized by U.S. * Government. Proscribed countries are set forth in the U.S. Export * Administration Regulations. Countries subject to U.S embargo are: Cuba, * Iran, Iraq, Libya, North Korea, Syria, and the Sudan. This list is subject * to change without further notice from SwRI, and you must comply with the * list as it exists in fact. You certify that you are not on the U.S. * Department of Commerce's Denied Persons List or affiliated lists or on the * U.S. Department of Treasury's Specially Designated Nationals List. You agree * to comply strictly with all U.S. export laws and assume sole responsibilities * for obtaining licenses to export or reexport as may be required. * * General * * These Terms represent the entire understanding relating to the use of the * Software and prevail over any prior or contemporaneous, conflicting or * additional, communications. SwRI can revise these Terms at any time * without notice by updating this posting. * * Trademarks * * The SwRI logo is a trademark of SwRI in the United States and other countries. * */ #ident "@(#) read_drec.c 1.40 05/08/19 SwRI" #include #include "ret_codes.h" #include "gen_defs.h" #include "libbase_idfs.h" #include "libVIDF.h" /* for header format comparison */ /**************************************************************************** * * * READ_DREC SUBROUTINE * * * * DESCRIPTION * * This is the read routine used by all instruments. The sensor, sweep, * * and calibration data for the data set of interest is retrieved, if * * applicable, and placed in the data structure that is allocated to hold * * the values to be returned to the user. All data is returned in * * telemetry units. In this way, one call for the sensor of interest can * * be made to this routine instead of one call per parameter for the same * * sensor. The returned data can be converted to other units by calling * * the routine CONVERT_TO_UNITS(). For this routine, the fwd flag * * determines when the NEXT time sample is to be processed. For a sweeping* * instrument, N_SAMPLE data elements are returned. For a scalar * * instrument, either a single or N_SAMPLE elements are returned, depending* * upon the FULL_SWP flag. If ALL sensors for a given data set are being * * requested, the user should set the fwd flag to 1 for the last sensor in * * the group, the rest should use a 0 for the fwd flag. This ensures that * * all data taken at the same time will be processed before advancing to * * the next time sample. * * * * INPUT VARIABLES * * SDDAS_ULONG data_key key which uniquely identifies the data set * * being processed * * SDDAS_CHAR *exten filename extension for the data to be used * * SDDAS_USHORT vnum version number to be associated with this * * combination (allows for multiple opens) * * void *idf_data_ptr ptr to memory location for the structure * * that holds returned data values (read_drec)* * SDDAS_SHORT sen the sensor for which data is requested * * SDDAS_CHAR fwd flag that indicates when to advance to the * * time sample * * SDDAS_CHAR full_swp request 1 or all values in sensor set be * * returned (for scalar parameters only) * * * * USAGE * * x = read_drec (data_key, exten, vnum, idf_data_ptr, sen, fwd, * * full_swp) * * * * NECESSARY SUBPROGRAMS * * strcpy() copies a string to another string variable * * ir_locate_ex() determines if requested combination has * * already been pand points to the * * correct structure allocated for the combo * * ir_next_idf_file() determines if a new VIDF file needs to be * * opened and utilized for the data set being * * processed * * ir_reset_header() sets data elements that are dependent upon * * the information in the header file * * ir_new_data_record () retrieves the next data record * * ir_new_header_record () retrieves the next header record * * ir_read_drec_times () fills in the time values returned by this * * module * * ir_read_drec_time_advance () advances to the next time sample * * ir_read_drec_data_values () retrieves data for sensor requested * * ir_set_last_time_values () sets the time values to the last time * * calculated in case of error conditions * * * * EXTERNAL VARIABLES * * struct general_info structure holding information concerning * * ginfo the experiment that is being processed * * SDDAS_CHAR ir_reset_sensors flag indicating if a new header was read,* * in which case, new sensors may be returned * * SDDAS_CHAR ir_block_adv flag indicating if time advancement should * * be blocked * * * * INTERNAL VARIABLES * * struct idf_data *EXP_DATA structure that holds all of the currently * * returned data values to be processed * * struct experiment_info a pointer to the structure that holds * * *ex specific experiment information * * struct ptr_rec *ptr a pointer to the structure which holds all * * pointers to the header and data for the * * experiment of interest * * struct pitch_info a pointer to the structure that holds pitch* * *pa_ptr angle information * * struct potential_info a pointer to the structure that holds space* * *potential_ptr craft potential information * * struct euler_info a pointer to the structure that holds euler* * *pmi_ptr angle information * * struct celestial_info a pointer to the structure that holds * * *cp_ptr celestial position information * * struct background_info a pointer to the structure that holds back-* * *bkgd_ptr ground information * * register SDDAS_LONG *l1 pointer to long variables * * register SDDAS_SHORT *s1 pointer to SDDAS_SHORT variables * * reg SDDAS_SHORT *s_end loop termination variable * * reg SDDAS_UCHAR *uc1 pointer to process mode values * * reg SDDAS_UCHAR *uc_end loop termination variable * * SDDAS_LONG sen_index index value that tells the position of the * * sensor within the sensors returned * * SDDAS_LONG hdr_offset indicates which header record to access * * SDDAS_SHORT rval holds called routine status flags * * SDDAS_CHAR found_sensor flag indicating if the requested sensor is * * in the sensors returned and is associated * * with the time period being processed * * char reset_called flag indicating if LOCATE_EX was called * * * * SUBSYSTEM * * Display Level * * * ***************************************************************************/ SDDAS_SHORT read_drec (SDDAS_ULONG data_key, SDDAS_CHAR *exten, SDDAS_USHORT vnum, void *idf_data_ptr, SDDAS_SHORT sen, SDDAS_CHAR fwd, SDDAS_CHAR full_swp) { extern struct general_info ginfo; extern SDDAS_CHAR ir_reset_sensors, ir_block_adv; struct idf_data *EXP_DATA; struct experiment_info *ex; struct ptr_rec *ptr; struct pitch_info *pa_ptr; struct potential_info *potential_ptr; struct euler_info *pmi_ptr; struct celestial_info *cp_ptr; struct background_info *bkgd_ptr; register SDDAS_LONG *l1; register SDDAS_SHORT *s1, *s_end; register SDDAS_UCHAR *uc1, *uc_end; SDDAS_LONG sen_index, hdr_offset; SDDAS_SHORT rval; SDDAS_CHAR found_sensor; char reset_called; /****************************************************************************/ /* Since void pointer, make sure correct type of data structure being used.*/ /* Data structures define the same elements at the beginning of the */ /* structure definition. */ /****************************************************************************/ EXP_DATA = (struct idf_data *) idf_data_ptr; if (EXP_DATA->header_format != ORIGINAL_HEADER) return (WRONG_DATA_STRUCTURE); /*************************************************************************/ /* Check to see if the combination being processed has been processed */ /* before. If not, an error condition - probably didn't call FILE_OPEN. */ /* Since ir_locate_ex() is called by more than one routine, return an */ /* error code that indicates which calling routine resulted in the error.*/ /* Since a 0 is passed for the last parameter, the only possible error is*/ /* that the requested combination was not found among processed combos. */ /*************************************************************************/ EXP_DATA->filled_data = 0; if (!ginfo.called_locate) { rval = ir_locate_ex (data_key, exten, vnum, 0); if (rval != ALL_OKAY) return (DREC_NOT_FOUND); ginfo.called_locate = 1; reset_called = 1; } else reset_called = 0; /************************************************************************/ /* Check file descriptors for the data and header files. If either of */ /* the file descriptors is less than 0, the file has not been opened. */ /************************************************************************/ ex = ginfo.expt; if (ex->header_format != ORIGINAL_HEADER) return (WRONG_HEADER_FORMAT); if (ex->fdh < 0 || ex->fdd < 0) { if (reset_called) ginfo.called_locate = 0; return (DREC_NO_FILES); } ptr = ex->info_ptr; ptr->time_advanced = 0; if (ptr->chg_sen_set) EXP_DATA->hdr_change = 0; ir_reset_sensors = 0; /**************************************************************************/ /* Was there a problem reading from the data file last time? Send the */ /* DREC_EOF flag to ir_new_header_record() to be sure that the same */ /* status is used by both routines. Send no_sensor to new_data_record */ /* and new_header_record so return code will be DREC_EOF_NO_SENSOR if */ /* data still not there since no data contained in EXP_DATA to be plotted.*/ /**************************************************************************/ if (ex->drec_eof != 0) { ex->drec_eof = 0; if ((rval = ir_new_data_record (0)) != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; ir_set_last_time_values (idf_data_ptr); return (rval); } if ((rval = ir_new_header_record (0, idf_data_ptr)) != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; ir_set_last_time_values (idf_data_ptr); return (rval); } ir_reset_sensors = 1; } /************************************************************************/ /* Was there a problem reading from the header file last time? */ /************************************************************************/ if (ex->hrec_eof != 0) { ex->hrec_eof = 0; if ((rval = ir_new_header_record (0, idf_data_ptr)) != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; ir_set_last_time_values (idf_data_ptr); return (rval); } ir_reset_sensors = 1; } /************************************************************************/ /* Find the position of the sensor requested in the sensor index array. */ /************************************************************************/ found_sensor = 0; l1 = &sen_index; s1 = ptr->SENSOR_INDEX; s_end = s1 + *ptr->N_SEN; for (*l1 = 0; s1 < s_end; ++(*l1), ++s1) if (*s1 == sen) { found_sensor = 1; if (ex->sen_mode < 2 || ex->sen_mode == 4 || ex->sen_mode == 5) { if (*l1 != ptr->time_col) found_sensor = 0; } break; } /*************************************************************************/ /* Was a new header read on the previous call to this routine? If so, */ /* certain data elements need to be reset. */ /*************************************************************************/ if (ptr->reset_hdr) { /**********************************************************************/ /* This check is made in two places to facilitate plotting of data. */ /* (allow the plotting of a partial sweep) */ /**********************************************************************/ hdr_offset = (*ptr->NSS > 0) ? *(ptr->HDR_OFF + ptr->cur_sen_set) : *(ptr->HDR_OFF + 0); if (hdr_offset == NO_MORE_DATA) { if (reset_called) ginfo.called_locate = 0; ir_set_last_time_values (idf_data_ptr); return (LOS_STATUS); } else if (hdr_offset == NEXT_FILE) { if (reset_called) ginfo.called_locate = 0; ir_set_last_time_values (idf_data_ptr); return (NEXT_FILE_STATUS); } if ((rval = ir_reset_header (idf_data_ptr, sen, full_swp)) != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; ir_set_last_time_values (idf_data_ptr); return (rval); } } /**************************************************************************/ /* These two fields are updated if a header changes, but if the user is */ /* swapping between various virtuals, or the same virtual, but different */ /* time spans, and a header change was not detected for the virtual in */ /* question, user gets wrong YEAR/DAY values being returned. */ /**************************************************************************/ else { EXP_DATA->byear = *ptr->YEAR; EXP_DATA->bday = *ptr->DAYOFYEAR; EXP_DATA->eyear = *ptr->YEAR; EXP_DATA->eday = *ptr->DAYOFYEAR; EXP_DATA->mode_byear = *ptr->YEAR; EXP_DATA->mode_bday = *ptr->DAYOFYEAR; EXP_DATA->mode_eyear = *ptr->YEAR; EXP_DATA->mode_eday = *ptr->DAYOFYEAR; /***********************************************************************/ /* Set the beginning time and ending time for this time sample. */ /* Adjust the time components for day boundary crossings. The byear */ /* and eyear elements are the same value BEFORE time adjustment. */ /***********************************************************************/ ir_read_drec_times (idf_data_ptr, sen, full_swp); } /* At this point, the individual time elements have been set. */ /*************************************************************************/ /* Instrument mode flags and sample sequence data are returned every read*/ /* RESET_HEADER() allocates/reallocates space to hold sample seq. data. */ /* Even though changed N_SAMPLE to SDDAS_USHORT, did not change */ /* NUM_SWP_STEPS cause would have forced binning and more importantly, */ /* hdr_size to change. Since hdr_size uses negative numbers, would have */ /* to change to long, which would cause reprocessing of ALL data sets. */ /* Changing N_SAMPLE to SDDAS_USHORT was needed for a scalar inst. */ /*************************************************************************/ EXP_DATA->num_swp_steps = (ex->smp_id == 2) ? 1 : *ptr->hdr_fmt1_ptr->N_SAMPLE; l1 = EXP_DATA->swp_data; s1 = ptr->hdr_fmt1_ptr->SAMP_INDEX; s_end = s1 + EXP_DATA->num_swp_steps; for (; s1 < s_end; ++l1, ++s1) *l1 = *s1; /************************************************************************/ /* For optimization purposes, it's advised to use ++x instead of x++. */ /************************************************************************/ l1 = EXP_DATA->mode; uc1 = ptr->MODE_INDEX; uc_end = uc1 + *ptr->I_MODE; for (; uc1 < uc_end; ++l1, ++uc1) *l1 = *uc1; EXP_DATA->mode_len = *(ptr->I_MODE); /*************************************************************************/ /* If the sensor was found, retrieve the sensor data and any calibration*/ /* data for the requested sensor. */ /*************************************************************************/ if (found_sensor) { EXP_DATA->d_qual = (SDDAS_LONG) *(ptr->DQUAL + sen_index); rval = ir_read_drec_data_values (idf_data_ptr, sen, fwd, full_swp, sen_index); if (rval != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; return (rval); } } else { EXP_DATA->d_qual = -1; /* set to -1 to mean BOGUS value since 0-255 */ /***********************************************************************/ /* If read_drec was called with the time advancement flag set, reset */ /* the ancillary data retrieval flag(s) for NEXT call. In this way, */ /* even though sensor was not found, it is consistent with the */ /* read_drec time advancement philosophy for all ancillary data. */ /***********************************************************************/ if (fwd) { ex->swp_times.get_times = 1; /* Calculate pitch angles? */ if (ex->pa_def && ex->bmem.base_pitch_info != NO_MEMORY) { if (ex->return_pitch_angles == sTrue) { pa_ptr = ex->pitch_angles; if (pa_ptr->pa_format == PA_COMPUTE) pa_ptr->get_pa_data = 1; } } /* Calculate spacecraft potential values. */ if (ex->potential_def && ex->bmem.base_potential_info != NO_MEMORY) { /* There is no return boolean flag (turn on/off) associated */ /* with spacecraft potential data since, IF it is defined, it */ /* is used to correct sensor/sweep data. */ potential_ptr = ex->potential; if (potential_ptr->scpot_format == SCPOT_DSRC) potential_ptr->get_potential_data = 1; } /* Calculate euler angles? */ if (ex->euler_def && ex->bmem.base_euler_info != NO_MEMORY) { if (ex->return_euler_angles == sTrue) { pmi_ptr = ex->euler_angles; if (pmi_ptr->pmi_format == EULER_DSRC) pmi_ptr->get_pmi_data = 1; } } /* Calculate celestial position data? */ if (ex->celestial_def && ex->bmem.base_celestial_info != NO_MEMORY) { if (ex->return_celestial_pos == sTrue) { cp_ptr = ex->celestial_position; if (cp_ptr->cp_format == CELESTIAL_DSRC) cp_ptr->get_cp_data = 1; } } /* Calculate background values. */ if (ex->background_def && ex->bmem.base_background_info != NO_MEMORY) { /* There is no return boolean flag (turn on/off) associated */ /* with background data since, IF it is defined, it is used */ /* to correct sensor data. */ bkgd_ptr = ex->background; if (bkgd_ptr->background_format == BKGD_DSRC) bkgd_ptr->get_background_data = 1; } } } /*************************************************************************/ /* If more than 1 IDF file is to be utilized, check the time to see if */ /* the next IDF file should be read. Be sure to reset ex structure */ /* since VIDF file crossing may mean a reallocation of the existing ex */ /* structures so address may change (do this regardless of error code). */ /*************************************************************************/ if (ex->de_year != -1) { rval = ir_next_idf_file (EXP_DATA->bmilli, EXP_DATA->bnano); ex = ginfo.expt; if (rval != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; return (rval); } } /*************************************************************************/ /* Save various data elements associated with this call to the generic */ /* read routine. */ /*************************************************************************/ ex->last_sensor = sen; EXP_DATA->data_key = data_key; EXP_DATA->version = vnum; EXP_DATA->sensor = sen; EXP_DATA->spin_rate = *(ptr->SPIN); EXP_DATA->sun_sen = *(ptr->SUN_SEN); strcpy (EXP_DATA->exten, exten); /******************************************************************/ /* Do we need to advance the pointers to the next time sample? */ /******************************************************************/ if (fwd && (!ir_reset_sensors || !ir_block_adv)) { rval = ir_read_drec_time_advance (idf_data_ptr, sen, full_swp, found_sensor); if (rval != ALL_OKAY) { if (reset_called) ginfo.called_locate = 0; return (rval); } } /*************************************************************************/ /* If the sensor requested was not found, return a different code from */ /* code meaning the sensor was found and data is being returned. */ /*************************************************************************/ if (reset_called) ginfo.called_locate = 0; if (!found_sensor) return (DREC_NO_SENSOR); else return (ALL_OKAY); }