ReadPidf

Introduction to ReadPidf
ReadPidf basics
Information available from the PIDF

Introduction to ReadPidf

SYNOPSIS

The ReadPidf calls are necessary if you ever need to read information from the PIDF. The PIDF holds valuable information about the instrument which may be needed for calculation or plotting purposes.

This document makes no attempt at educating the user on the PIDF or how the information is used in the PIDF. See the PIDF Documention if you need to know about a certain field. This document only serves as a way of getting information you already know exists in the PIDF.

Most information in the PIDF is in a structured form. If you know which particular structure the information is in, you can go straight to that data type and see how to get at that information.

ReadPidf

SYNOPSIS

This routine reads from Plot Information Definition Files (PIDF) v2.0 to return specific data requested into storage provided by the calling routine.

include "pidf_defs.h"'

int ReadPidf (unsigned long data_key,
                 char          *exten,
                 int           data_type,
                 int           sennum,
                 int           unitnum,
                 PIDF          what,
                 char          *memory)

ARGUMENTS

data_key is a unique value which indicates the data set of interest.

exten is a two character extension to be added to PIDF file names when default files are not to be used.

data_type is the data type of the value requested.

sennum is a data type identification number for accessing values that iterate (typically this is a number which specifies which structure you wish to look at).

unitnum is the unit identification number (if needed).

what is the requested item from data_type.

memory is adequate memory of the correct data type casted to a a character pointer for answers to be placed.

DESCRIPTION

ReadPidf is the generic PIDF data read routine, that interfaces the data and presentation routines. Plotting defaults are made available to the calling program for the configuration of plotting packages.

The data set of interest is referenced through the key value data_key which must be created using the fields_to_key module. Most of the IDFS generic routines utilize key values. The routine returns information about the various data types sensor, sweep, calibration, mode, data quality, pitch angle and spin angle upon request.

The exten field currently is not used.

The mnemonics for data_type are found in pidf_defs.h. sennum and unitnum are PIDF assigned numbers for the item you are seeking information about. What is the specific item you are interested in given the previous parameters. The mnemonics for what is also found in pidf_defs.h. Argument memory is a casted character pointer of the correct data type.

ReadPidf uses a hashing mechanism to store PIDF files in memory for efficient access.

When one of these files is updated, ReadPidf will re-hash the changes so the user does not have to restart their program for the changes to take effect.

ReadPidf will also attempt to AutoPromote(3) pidf files when they are off line.

ERRORS

All errors within this routine are returned through the status variable.

The header file pidf_ret.h, which includes all possible return values, should be included so that the mnemonics for the return codes can be referenced. The pidf_ret.h file is described below. If the error is related to the syntax of the PIDF file, then the line number of the error and full path name are printed.

WARNINGS

No memory bounds checking is done on the caller supplied memory. Therefore, sufficient memory should be given to avoid serious error.

EXAMPLES

Obtain the sensor name for sensor 2 in the virtual instrument MPSB, which is part of the PEM experiment on the MEPS instrument. The PEM experiment is part of the UARS-1 mission, which is identified with the UARS project.

include "pidf_defs.h"

extern LinkList Projects;

StrHier pcode, mcode, ecode, icode, vcode;
ulong data_key;
short project, mission, exper, inst, vinst, params[5], status;
char sen_name[100];

pcode = SourceByStr (Projects, "UARS", (char *) 0);
project = SNUM (pcode);

mcode = SourceByStr (Projects, "UARS", "UARS-1", (char *) 0);
mission = SNUM (mcode);

ecode = SourceByStr (Projects, "UARS", "UARS-1", "PEM", (char *) 0);
exper = SNUM (ecode);

icode = SourceByStr (Projects, "UARS", "UARS-1", "PEM", "MEPS", (char *) 0);
inst = SNUM (icode);

vcode = SourceByStr (Projects, "UARS", "UARS-1", "PEM", "MEPS", "MPSB", (char *) 0);
vinst = SNUM (vcode);

params[0] = project;
params[1] = mission;
params[2] = exper;
params[3] = inst;
params[4] = vinst;
fields_to_key (params, &data_key);

status = ReadPidf(data_key, "", SENSOR, 2, NOTUSED, NAME, (char*) sen_name);

Averaging Information Datatypes

SYNOPSIS

AVG, MASS, CHARGE, PHI, THETA, or SCAN

Each of these will get averaging information from the PIDF if it is available. To get MASS, CHARGE, PHI, THETA, or SCAN info, use the related keyword as your datatype with START or STOP as your what value.

USES

Possible what values for AVG :

DIMEN - will retrieve PIDF field instrument_dep.
DEPEN - will retrieve PIDF field cyclic.

Possible what values for MASS, CHARGE, PHI, THETA, or SCAN :

START - will retrieve PIDF field *_min.
STOP - will retrieve PIDF field *_max.

where * is one of MASS, CHARGE, PHI, THETA, or SCAN

Binning Datatype

SYNOPSIS

BIN

Will get binning information from the PIDF.

USES

Possible what values :

BINMETHOD - retrieves PIDF field method from the Bin struct.
NUMBININDEX,
NSETS - retrieves PIDF field num_bin_sets.
NUMOF - retrieves PIDF field num_bins from the Bin struct.
SPACING - retrieves PIDF field bin_scaling from the Bin struct.
START - retrieves PIDF field min from the Bin struct.
STOP - retrieves PIDF field max from the Bin struct.

All information in the Bin struct requires an associate bin number. This is specified as sennum in the call to ReadPidf.

Calibration Data Datatype

SYNOPSIS

CAL_DATA

Will get calibration information from the PIDF.

USES

Possible what values :

MODIFY - retrieves PIDF field cal_modify_flag from the CalSet struct.
NAME - retrieves PIDF field name from the CalSet struct.
NAMES - retrieves PIDF fields name from all CalSet structs. (*)
NSETS - retrieves PIDF field number_cal_sensors from the CalSet struct.
NUMOF - retrieves PIDF field num_cals.
NUNITS - retrieves PIDF field num_units from the CalSet struct.
PIDFNUM - retrieves PIDF field pidf_cal_num from the CalSet struct.
PIDFNUMS - retrieves PIDF fields pidf_cal_num from all the CalSet structs. (*)
SENSETS - retrieves PIDF field cal_based_on_sensor from the CalSet struct.
SHORTNAME - retrieves PIDF field short_name from the CalSet struct.
UNITNUMS - retrieves PIDF fields unit_number from the CalSet struct.
VIDFNUM - retrieves PIDF field vidf_cal_num from the CalSet struct.
VIDFNUMS - retrieves PIDF fields vidf_cal_num from all the CalSet structs. (*)
SRCFLAG - retrieves PIDF field source from the CalSet struct.

All information in the CalSet struct requires an associated calibration number. This is specified as sennum in the call to ReadPidf.

Data Quality Datatype

SYNOPSIS

D_QUAL

Will get data quality information from the PIDF.

USES

Possible what values :

NAME,
NAMES - retrieves PIDF field name from the DataQual struct.
NUNITS - retrieves PIDF field num_units from the DataQual struct.
SHORTNAME - retrieves PIDF field short_name from the DataQual struct.
UNITNUMS - retrieves PIDF fields unit_number from the DataQual struct.

PIDF Group Datatype

SYNOPSIS

PIDF_GROUP

Will get grouping information from the PIDF.

USES

Possible what values :

COMPNAMES - returns the names of the components in a given group number. (*)
NAMES - retrieves PIDF fields group_name.
NUMINGRP - returns the number of sensors in a given group number. (*)
NUMOF - retrieves PIDF field num_groups.
SENNAMES - returns the names of the sensors in a given group number. (*)

Items without Datatype

SYNOPSIS

Certain information is available without needing an associated data type. For these pieces of information, send in NOTUSED for the datatype, sennum and the unitnum.

USES

Possible what values :

EXP - retrieves PIDF field experiment.
FLOWINTO - retrieves PIDF field flow_into.
INST - retrieves PIDF field instrument.
INSTITUTE - retrieves PIDF field institute.
MASK - retrieves PIDF fields data_type_mask.
MISS - retrieves PIDF fields mission.
PLTAVL - retrieves PIDF field plot_avail_flag.
PROJ - retrieves PIDF fields project.
VERSION - retrieves PIDF fields version.
VINST - retrieves PIDF fields vinst.

Mode Datatype

SYNOPSIS

MODE

Will get mode information from the PIDF.

USES

Possible what values :

NAME - retrieves PIDF field name from the Mode struct.
NAMES - retrieves PIDF fields name from all the Mode structs. (*)
NUMOF - retrieves PIDF field num_modes.
NUNITS - retrieves PIDF field num_units from the Mode struct.
PIDFNUM - retrieves PIDF field pidf_mode_num from the Mode struct.
PIDFNUMS - retrieves PIDF field pidf_mode_num from all the Mode structs. (*)
SHORTNAME - retrieves PIDF field short_name from the Mode struct.
UNITNUMS - retrieves PIDF fields unit_number from the Mode struct.
VIDFNUM - retrieves PIDF field vidf_mode_num from the Mode struct.
VIDFNUMS - retrieves PIDF field vidf_mode_num from all the Mode structs. (*)

All information in the Mode struct requires an associated mode number. This is specified as sennum in the call to ReadPidf.

Pitch Angle Datatype

SYNOPSIS

PITCH_ANGLE

Will get pitch angle information from the PIDF.

USES

Possible what values :

NAME,
NAMES - retrieves PIDF field name from the PitchAngle struct.
NUNITS - retrieves PIDF field num_units from the PitchAngle struct.
SHORTNAME - retrieves PIDF field short_name from the PitchAngle struct.
UNITNUMS - retrieves PIDF fields unit_number from the PitchAngle struct.

All information in the PitchAngle struct requires an associated sensor number. This is specified as sennum in the call to ReadPidf.

Sensor Datatype

SYNOPSIS

SENSOR

Will get sensor information from the PIDF.

USES

Possible what values :

BININDEX - retrieves PIDF field binning_index from the Sensor struct.
COMPNAME - retrieves PIDF field component from the Sensor struct.
GRPNUM - retrieves PIDF field group_num from the Sensor struct.
NAME - retrieves PIDF field name from the Sensor struct.
NAMES - retrieves PIDF field name from all the Sensor structs. (*)
NUMOF - retrieves PIDF field num_sensors.
NUNITS - retrieves PIDF field num_units from the Sensor struct.
PIDFNUM - retrieves PIDF field pidf_sensor_num from the Sensor struct.
PIDFNUMS - retrieves PIDF field pidf_sensor_num from all the Sensor structs. (*)
SWPNDX - retrieves PIDF field scan_block_info from the Sensor struct.
UNITNUMS - retrieves PIDF fields unit_number from the Sensor struct.
VIDFNUM - retrieves PIDF field vidf_sensor_num from the Sensor struct.
VIDFNUMS - retrieves PIDF field vidf_sensor_num from all the Sensor structs. (*)
SRCFLAG - retrieves PIDF field source from the Sensor struct.

All information in the Sensor struct requires an associated sensor number. This is specified as sennum in the call to ReadPidf.

Spin (Start Azimuthal/Stop Azimuthal) Angle Datatype

SYNOPSIS

START_AZ_ANGLE and STOP_AZ_ANGLE

Will get spin angle information from the PIDF.

USES

Possible what values :

NAME,
NAMES - retrieves PIDF field name from the SpinAngle struct.
NUNITS - retrieves PIDF field num_units from the SpinAngle struct.
SHORTNAME - retrieves PIDF field short_name from the SpinAngle struct.
UNITNUMS - retrieves PIDF fields unit_number from the SpinAngle struct.

All information in the SpinAngle struct requires an associated sensor number. This is specified as sennum in the call to ReadPidf.

Sweep Step/Scan Datatype

SYNOPSIS

SWEEP_STEP or SCAN

Will get scan information from the PIDF.

Scan is a bit of an awkward one as it has seperate units within it as a different structure. As a result, most operations involve sending an associated scan number and a corresponding unit number.

USES

Possible what values :

NUMOF - retrieves PIDF field num_scan.
NUNITS - retrieves PIDF field num_units from the Scan struct.
SCANSCFSEN - retrieves PIDF field scan_scf_sensor from the ScanUnit struct within the Scan struct.
UNITNUM - retrieves PIDF fields units_index from the ScanUnit struct within the Scan struct.
UNITNUMS - retrieves PIDF fields units_index from all the ScanUnit structs within the Scan struct. (*)
UNITFMT - retrieves PIDF fields spacing from the ScanUnit struct within the Scan struct.
UNITFMTS - retrieves PIDF fields spacing from all the ScanUnit structs within the Scan struct. (*)
VARUNITNUM - retrieves PIDF fields var_units from the ScanUnit struct within the Scan struct.
VARUNITNUMS - retrieves PIDF fields var_units from all the ScanUnit structs within the Scan struct. (*)
VARUNITUBNUM - retrieves PIDF fields var_units_ub from the ScanUnit struct within the Scan struct.
VARUNITUBNUMS - retrieves PIDF fields var_units_ub from all the ScanUnit structs within the Scan struct. (*)
VARUNITFMT - retrieves PIDF fields bin_location from the ScanUnit struct within the Scan struct.
VARUNITFMTS - retrieves PIDF fields bin_location from all the ScanUnit structs within the Scan struct. (*)
VSCANSCFSEN - retrieves PIDF field v_scan_scf_sensor from the ScanUnit struct within the Scan struct.
VSCANUBSCFSEN - retrieves PIDF field v_scan_ub_scf_sensor from the ScanUnit struct within the Scan struct.

All information in the Scan struct requires an associated scan number. Information in the ScanUnit struct requires a related ScanUnit number within the Scan struct. The scan number is specified as sennum and the scan unit number is specified as unitnum in the call to ReadPidf.

Units from Datatypes

SYNOPSIS

UNITS

Will get unit information from the PIDF. Most data types have a units field within them and to get to the units information, one must go through the associated data type.

USES

Possible what values :

DEFAULTMAX - retrieves PIDF field max from the Unit struct.
DEFAULTMIN - retrieves PIDF field min from the Unit struct.
LONGDESC - retrieves PIDF field long_description from the Unit struct.
NUMTBLAPP - retrieves PIDF field num_tables from the Unit struct.
SCALING - retrieves PIDF field unit_scaling from the Unit struct.
SHORTDESC - retrieves PIDF field short_description from the Unit struct.
TABLEAPP - retrieves PIDF field tbl_app_flag from the Unit struct.
TBLAPPOPS - retrieves PIDF field tbl_app_oper from the Unit struct.
UNITID - retrieves PIDF field id from the Unit struct.
UNITLAB - retrieves PIDF field unit_label from the Unit struct.

All information in the Unit struct requires an associated unit number. This is specified as unitnum in the call to ReadPidf.

Moments Datatype

SYNOPSIS

MOMENTS

Will get plasma moments calculation information from the PIDF if it is available.

USES

Possible what values :

MOMENTSDEF - returns a value that indicates if plasma moments calculations are defined.
- 0 = plasma moments not defined.
- 1 = plasma moments defined.
MOMENTMASS - retrieves PIDF field moment_mass from the Moments struct.
VUNIT - retrieves PIDF field velocity_unit from the Moments struct.
VDIFFUNIT - retrieves PIDF field vel_diff_fun_unit from the Moments struct.
POTENTIALDEF - retrieves PIDF field potential_defined from the Moments struct.
SCPOTENTIAL - retrieves PIDF field spacecraft_potential from the Moments struct.
MOMENTCHARGE - retrieves PIDF field moment_charge from the Moments struct.

ReadPidf

Table of Contents

Introduction to ReadPidf

SYNOPSIS

ReadPidf

SYNOPSIS

ARGUMENTS

DESCRIPTION

ERRORS

WARNINGS

EXAMPLES

Averaging Information Datatypes

SYNOPSIS

USES

Binning Datatype

SYNOPSIS

USES

Calibration Data Datatype

SYNOPSIS

USES

Data Quality Datatype

SYNOPSIS

USES

PIDF Group Datatype

SYNOPSIS

USES

Items without Datatype

SYNOPSIS

USES

Mode Datatype

SYNOPSIS

USES

Pitch Angle Datatype

SYNOPSIS

USES

Sensor Datatype

SYNOPSIS

USES

Spin (Start Azimuthal/Stop Azimuthal) Angle Datatype

SYNOPSIS

USES

Sweep Step/Scan Datatype

SYNOPSIS

USES

Units from Datatypes

SYNOPSIS

USES

Moments Datatype

SYNOPSIS

USES