trek_user_api.h File Reference

The ANSI C version of the TReK Release API (trek_user_api). More...

#include <time.h>
#include "trek_error.h"

Macros
#define	API_INVALID_PACKET_TYPE   35001
	The packet type is not one of the allowed types: PDSS_PAYLOAD, GSE, CCSDS, SCS, PRCU, EXPRESS, GSE_MERGE, UFO, PDSS_CORE.
#define	API_INVALID_PARAMETER_TYPE   35002
	The parameter type is not of of the allowed types: EHS_PACKET, CCSDS_PACKET, MSID, EXPRESS, or UFO.
#define	API_INVALID_MSID   35004
	The parameter name is not valid.
#define	API_INVALID_DATA_MODE   35005
	The data mode is not one of the allowed modes.
#define	API_INVALID_APID   35006
	The APID is outside of the allowed range.
#define	API_TOO_MANY_SAMPLES   35007
	Not considered an error. Returned if the number of samples available is less than the number of samples requested.
#define	API_PARAMETER_NOT_FOUND   35008
	Parameter not found. Check the spelling of the parameter name. Also check that the packet type and data mode are correct.
#define	API_NO_DATA_AVAILABLE   35010
	Returned if there is no data available. This can occur when a packet has been initialized, but the TReK system has not yet received any packets of data containing the parameter.
#define	API_NO_NEW_DATA   35012
	Returned if there is no new data available.
#define	API_CALIBRATION_NOT_DEFINED   35013
	Calibration is not defined for this parameter.
#define	API_INCORRECT_DATATYPE   35014
	Returned if the data to be returned is not the correct datatype. For example, if using GetOne...IntegerValue() and data was actually a string then this error would be returned because this function only returns integer data.
#define	API_NOT_ENOUGH_SPACE   35016
	The memory allocated for the returned value is not large enough. Check the returned size of data to see what is the minimum needed.
#define	API_INVALID_LIMIT_ES_FLAG   35020
	The limit/expected state (LES) flag must be 0 (No LES sensing) or 1 (Check for LES errors)
#define	API_MEMORY_ERROR   35022
	General memory error. Could indicate a problem with data definition.
#define	API_DATA_SIZE_ERROR   35023
	Error associated with data size. Check metadata definition for accuracy.
#define	API_MORE_DATA_AVAILABLE   35024
	Returned if there is more data available for this parameter. This indicates that another GetNext... call can be made to retrieve new data.
#define	API_WAIT_FAILED   35029
	The API failed while waiting for TReK to return data. If you see this error, please contact the TReK help desk.
#define	API_WAIT_ABANDONED   35030
	The API abandoned waiting for TReK to return data. If you see this error, please contact the TReK help desk.
#define	API_WAIT_TIMEOUT   35031
	The API timed out while waiting for TReK to return data. This error could indicate that your computer is unable to process the amount of data being requested.
#define	API_ERROR_ATTACHING_THREAD   35032
	Not used anymore.
#define	API_UNKNOWN_RETURN_CODE   35033
	Not used anymore. The 'unknown' return code is passed back for help in understanding problems.

Functions
Raw/Unprocessed Data API Functions
This section addresses functions that can be used to retreive raw data. There are functions to retrieve raw data for an entire packet, a subset, or an MSID.
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestRawValue (int packet_type, int parameter_type, const char *identifier, const char *apid, int data_mode, long *token, long *size_of_data, unsigned char *value, char *status)
	Gets the newest available raw (unprocessed/binary) value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextRawValue (int packet_type, int parameter_type, const char *identifier, const char *apid, int data_mode, long *token, long *size_of_data, unsigned char *value, char *status)
	Gets the next available raw (unprocessed/binary) value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketRawValue (int packet_type, int parameter_type, const char *identifier, int data_mode, long *token, long *from_this_pkt_token, long *size_of_data, unsigned char *value, char *status)
	Gets the raw value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestRawValue (int packet_type, int parameter_type, const char *identifier, const char *apid, int data_mode, unsigned long *number_samples, long *token, long *size_of_data, unsigned char **value, char **status)
	This function provides a way to retrieve one or multiple samples of the newest raw value for a specified parameter. A parameter can be an entire packet, a subset, or an MSID. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextRawValue (int packet_type, int parameter_type, const char *identifier, const char *apid, int data_mode, unsigned long *number_samples, long *token, long *size_of_data, unsigned char **value, char **status)
	This function provides a way to retrieve one or multiple samples of the next raw value for a specified parameter. A parameter can be an entire packet, a subset, or an MSID. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketRawValue (int packet_type, int parameter_type, const char *identifier, int data_mode, unsigned long *number_samples, long *token, long *from_this_pkt_token, long *size_of_data, unsigned char **value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter as raw (unprocessed) data from the same packet as another parameter. A parameter can be an entire packet, a subset, or an MSID. More...
Converted Data API Functions
This section addresses functions that can be used to retrieve converted data. Each function is designed to retrieve data of a particular data type.
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestConvertedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, long *value, char *status)
	Gets the newest available integer value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestConvertedUnsignedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, unsigned long *value, char *status)
	Gets the newest available unsigned integer value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestConvertedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, double *value, char *status)
	Gets the newest available double value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestConvertedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, long *token, long *size_of_data, char *value, char *status)
	Gets the newest available string value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestConvertedTimeValue (int packet_type, const char *msid, const char *apid, int data_mode, long *token, TReK_Time *value, char *status)
	Gets the newest available time value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestConvertedTimeStringValue (int packet_type, const char *msid, const char *apid, int data_mode, long *token, long *size_of_data, char *value, char *status)
	Gets the newest available time string value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextConvertedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, long *value, char *status)
	Gets the next available integer value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextConvertedUnsignedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, unsigned long *value, char *status)
	Gets the next available unsigned integer value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextConvertedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, double *value, char *status)
	Gets the next available double value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextConvertedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, long *token, long *size_of_data, char *value, char *status)
	Gets the next available string value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextConvertedTimeValue (int packet_type, const char *msid, const char *apid, int data_mode, long *token, TReK_Time *value, char *status)
	Gets the next available time value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextConvertedTimeStringValue (int packet_type, const char *msid, const char *apid, int data_mode, long *token, long *size_of_data, char *value, char *status)
	Gets the next available time string value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketConvertedIntegerValue (int packet_type, const char *msid, int data_mode, int limit_es_flag, long *token, long *from_this_pkt_token, long *value, char *status)
	Gets the integer value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketConvertedUnsignedIntegerValue (int packet_type, const char *msid, int data_mode, int limit_es_flag, long *token, long *from_this_pkt_token, unsigned long *value, char *status)
	Gets the unsigned integer value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketConvertedDoubleValue (int packet_type, const char *msid, int data_mode, int limit_es_flag, long *token, long *from_this_pkt_token, double *value, char *status)
	Gets the double value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketConvertedStringValue (int packet_type, const char *msid, int data_mode, long *token, long *from_this_pkt_token, long *size_of_data, char *value, char *status)
	Gets the string value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketConvertedTimeValue (int packet_type, const char *msid, int data_mode, long *token, long *from_this_pkt_token, TReK_Time *value, char *status)
	Gets the time value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketConvertedTimeStringValue (int packet_type, const char *msid, int data_mode, long *token, long *from_this_pkt_token, long *size_of_data, char *value, char *status)
	Gets the time string value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestConvertedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is an integer. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestConvertedUnsignedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, unsigned long *value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is an unsigned integer. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestConvertedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, double *value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is a floating point. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestConvertedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, long *token, long *size_of_data, char **value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is a string. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestConvertedTimeValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, long *token, TReK_Time *value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is a time. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextConvertedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is an integer. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextConvertedUnsignedIntegerValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, unsigned long *value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is an unsigned integer. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextConvertedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, double *value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is a floating point. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextConvertedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, long *token, long *size_of_data, char **value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is a string. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextConvertedTimeValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, long *token, TReK_Time *value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is a time. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketConvertedIntegerValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *from_this_pkt_token, long *value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as an integer. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketConvertedUnsignedIntegerValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *from_this_pkt_token, unsigned long *value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as an unsigned integer. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketConvertedDoubleValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *from_this_pkt_token, double *value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as a double. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketConvertedStringValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, long *token, long *from_this_pkt_token, long *size_of_data, char **value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as a character string. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketConvertedTimeValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, long *token, long *from_this_pkt_token, TReK_Time *value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as a time value. The time value is returned via a TReK_Time structure. The definition of the TReK_Time structure is located in the trek.h file. The TReK_Time structure contains a variable that is a tm_time structure. The tm_time structure is defined in the C Run-time library. More...
Calibrated Data API Functions
This section addresses functions that can be used to retrieve converted data. Each function is designed to retrieve data of a particular data type.
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestCalibratedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, double *value, char *status)
	Gets the newest available calibrated double value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNewestCalibratedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, long *size_of_data, char *value, char *status)
	Gets the newest available calibrated string (enumerator) value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextCalibratedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, double *value, char *status)
	Gets the next available calibrated double value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneNextCalibratedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, int limit_es_flag, long *token, long *size_of_data, char *value, char *status)
	Gets the next available calibrated string (enumerator) value for the specified parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketCalibratedDoubleValue (int packet_type, const char *msid, int data_mode, int limit_es_flag, long *token, long *from_this_pkt_token, double *value, char *status)
	Gets the calibrated double value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOneSamePacketCalibratedStringValue (int packet_type, const char *msid, int data_mode, int limit_es_flag, long *token, long *from_this_pkt_token, long *size_of_data, char *value, char *status)
	Gets the calibrated string value for the specified parameter from the same packet as another parameter. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestCalibratedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, double *value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when calibrated is a floating point. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestCalibratedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *size_of_data, char **value, char **status)
	This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when calibrated is a string. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextCalibratedDoubleValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, double *value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when calibrated is a floating point. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextCalibratedStringValue (int packet_type, const char *msid, const char *apid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *size_of_data, char **value, char **status)
	This function provides a way to retrieve one or multiple next sample(s) for a parameter that when calibrated is a string. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketCalibratedDoubleValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *from_this_pkt_token, double *value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is calibrated as a double. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetSamePacketCalibratedStringValue (int packet_type, const char *msid, int data_mode, unsigned long *number_samples, int limit_es_flag, long *token, long *from_this_pkt_token, long *size_of_data, char **value, char **status)
	This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is calibrated as a character string. More...
General API Functions
These functions do not fit in the other categories.
int EXPORT_THIS_ANSI_C_FUNCTION	GetAPIReturnCodeAsString (int api_code, long size_of_data, char *message)
	This function provides a way to retrieve a string value that corresponds to an API integer value return code. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetPacketArrivalEventName (int packet_type, const char *apid, int data_mode, char **event_name)
	This function gets the event name associated with packet arrival. This string can be used with the WaitForPacketArrival() function. When a packet arrives the WaitForPacketArrival() function releases and you can get new data from the packet. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetParameterInformation (int packet_type, const char *msid, int data_mode, const char *processing_flag, Measurement_Properties *meas_prop)
	This function provides a way to retrieve parameter information about a MSID. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNewestDatazone (int packet_type, const char *apid, int data_mode, long *token, long *size_of_data, unsigned char *value, char *status)
	Gets the newest available data zone for the specified packet. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetNextDatazone (int packet_type, const char *apid, int data_mode, long *token, long *size_of_data, unsigned char *value, char *status)
	Gets the next available data zone for the specified packet. More...
int EXPORT_THIS_ANSI_C_FUNCTION	WaitForPacketArrival (const char *event_name, unsigned int timeout)
	This function waits for the event name retunred from the WaitForPacketArrival() function. When a packet arrives function returns and you can get new data from the packet. More...
int EXPORT_THIS_ANSI_C_FUNCTION	UnregisterPacketArrivalEvent (int packet_type, const char *apid, int data_mode, const char *event_name)
	Removes the specified event name associated with packet arrival. More...
int EXPORT_THIS_ANSI_C_FUNCTION	InitializeMultipleParameters (int packet_type, int data_mode, Multiple_Add_Struct *add_struct, unsigned long number_parameters)
	This function immediately returns SUCCESS. More...
int EXPORT_THIS_ANSI_C_FUNCTION	GetOverallStatus (int packet_type, const char *msid, int data_mode, const long *token, unsigned long *overall_status)
int EXPORT_THIS_ANSI_C_FUNCTION	SetMonitorLogFile (const char *filename)
	This function sets the filename for writing monitoring messages for archival. The filename should include the full directory path. When the file is created a timestamp is appended to the name and a ".log" extension is added after the timestamp. More...
int EXPORT_THIS_ANSI_C_FUNCTION	StartMonitorLogging ()
	This function starts logging of monitoring messages. Only messages occurring after the function call will be written to the file. More...
int EXPORT_THIS_ANSI_C_FUNCTION	StopMonitorLogging ()
	This function stops logging of monitoring messages. More...

Detailed Description

The ANSI C version of the TReK Release API (trek_user_api).

Function Documentation

GetAPIReturnCodeAsString()

int EXPORT_THIS_ANSI_C_FUNCTION GetAPIReturnCodeAsString	(	int	api_code,
		long	size_of_data,
		char *	message
	)

This function provides a way to retrieve a string value that corresponds to an API integer value return code.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	api_code	The API integer value return code.
[in]	size_of_data	This parameter is an Input parameter. This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	message	On SUCCESS this parameter will contain the message string.

Returns

SUCCESS

API_NOT_ENOUGH_SPACE (Release 3 return code)

Example:

int ret_value;
long token[3];
long value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
// ignoring return code for next function since the only failure is not enough memory and we're using the provide macro
char message[RETURN_CODE_STR_LEN];
GetAPIReturnCodeAsString( ret_value, RETURN_CODE_STR_LEN, message );
 
printf( "API Return Code: %s\n", message );

Longer examples that include this method:
None

GetNewestCalibratedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestCalibratedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when calibrated is a floating point.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the double integer values.
value = (double *)malloc(sizeof(double)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNewestCalibratedDoubleValue( PDSS_PAYLOAD, "MSID106", "7", REAL_TIME, &num_samples, SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %lf.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestCalibratedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestCalibratedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	size_of_data,
		char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when calibrated is a string.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char **value;
unsigned int ii, sample;
long size_of_data;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the string values.
//Create the 2D Array to hold the status strings for each sample. 
value = (char **)malloc(sizeof(char **)*num_samples);
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    value[sample] = (char *)malloc(100);        // assume 100 character max (including NULL)
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
size_of_data = 100;
ret_value = GetNewestCalibratedStringValue( PDSS_PAYLOAD, "MSID079", "7", REAL_TIME, &num_samples, LES_SENSE, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %s.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestConvertedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestConvertedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is a floating point.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the double integer values.
value = (double *)malloc(sizeof(double)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNewestConvertedDoubleValue( PDSS_PAYLOAD, "MSID106", "7", REAL_TIME, &num_samples, NO_SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %lf.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestConvertedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestConvertedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is an integer.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 3;
 
// Create the array to hold the integer values.
value = (long *)malloc(sizeof(long)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID107", "7", REAL_TIME, &num_samples, NO_SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %d.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestConvertedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestConvertedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	size_of_data,
		char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is a string.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char **value;
unsigned int ii, sample;
long size_of_data;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the string values.
//Create the 2D Array to hold the status strings for each sample. 
value = (char **)malloc(sizeof(char **)*num_samples);
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    value[sample] = (char *)malloc(100);        // assume 100 character max (including NULL)
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
size_of_data = 100;
ret_value = GetNewestConvertedStringValue( PDSS_PAYLOAD, "MSID127", "7", REAL_TIME, &num_samples, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %s.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestConvertedTimeValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestConvertedTimeValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		TReK_Time *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is a time.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
TReK_Time *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the time values.
value = (TReK_Time *)malloc(sizeof(TReK_Time)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNewestConvertedTimeValue( PDSS_PAYLOAD, "MSID128", "7", REAL_TIME, &num_samples, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Sample %u:  %04u-%02u-%02u %02u:%02u:%02u.  Status is %s.\n", ii, 
                            value[ii].tm_time.tm_year + 1900, 
                            value[ii].tm_time.tm_mon + 1, 
                            value[ii].tm_time.tm_mday, 
                            value[ii].tm_time.tm_hour, 
                            value[ii].tm_time.tm_min, 
                            value[ii].tm_time.tm_sec, 
                            status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestConvertedUnsignedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestConvertedUnsignedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		unsigned long *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple newest sample(s) for a parameter that when converted is an unsigned integer.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned long *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the unsigned integer values.
value = (unsigned long *)malloc(sizeof(unsigned long)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNewestConvertedUnsignedIntegerValue( PDSS_PAYLOAD, "MSID107", "7", REAL_TIME, &num_samples, NO_SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %u.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestDatazone()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestDatazone	(	int	packet_type,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		unsigned char *	value,
		char *	status
	)

Gets the newest available data zone for the specified packet.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for a single sample of the data that is being returned. The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, than you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned char value[10000];
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 10000;                   // reset this before each call to function
ret_value = GetNewestDatazone( PDSS_PAYLOAD, "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Size of data returned is %d.  Status is %s.\n", size_of_data, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNewestRawValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNewestRawValue	(	int	packet_type,
		int	parameter_type,
		const char *	identifier,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	size_of_data,
		unsigned char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of the newest raw value for a specified parameter. A parameter can be an entire packet, a subset, or an MSID.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	parameter_type	On a TReK System, any data aggregate is considered a parameter. Therefore packets, subsets, and MSIDs are all considered parameters. The parameter type argument identifies what type of parameter is being retrieved. The parameter_type information passed in should be one of the following values: CCSDS_PACKET, EHS_PACKET, SUBSET, or MSID. Please note that when you request to retrieve a CCSDS_PACKET, the API will return a complete CCSDS packet. This does not include the EHS header. You must pass in a parameter type of EHS_PACKET to retrieve the EHS header information.
[in]	identifier	The identifier for the parameter. The identifier is based on the parameter_type and should be one of the following: Parameter Type Identifier Should Be A(n) EHS_PACKET APID MSID MSID (Parameter) CCSDS_PACKET APID EXPRESS Source Function Code UFO User Assigned ID
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters.
int packet_type;
int parameter_type;
char identifier[MSID_LEN];
char apid[APID_LEN];
int data_mode;
unsigned long num_samples;
unsigned long sample;
long token[TOKEN_SIZE];
long size_of_data;
unsigned char **value;
unsigned char hex_pattern[DATA_LEN];
char **status;
int return_code;
int i;
long j;
unsigned long num_samp_allocated;
 
// Initialize or Assign Values to Input Parameters.
packet_type = PDSS_PAYLOAD;
parameter_type = MSID;
strcpy(identifier, "MSID038");
strcpy(apid, "");
data_mode = REAL_TIME;
num_samples = 3;
size_of_data = DATA_LEN;
num_samp_allocated = num_samples;
 
// Initialize the token for the first call. For all calls
// after the first call, don’t initialize the token, just  
// pass in the token that was returned from the previous call. 
 
for (i=0; i<TOKEN_SIZE; i++)
    token[i] = 0;
 
// Create the 2D Array to hold the raw value to be returned and initialize it to zero.   
value = (unsigned char **)malloc(sizeof(unsigned char **)
              *num_samples);
 
for (sample=0; sample< num_samp_allocated; sample++)
{
    value[sample] = (unsigned char*)malloc(size_of_data);
 
    for (j=0; j<size_of_data; j++)
    {
        value[sample][j] = 0;
    }
}
 
// Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample< num_samp_allocated; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
    strcpy(status[sample], " / / ");
}
 
// Call the API function.
return_code = GetNewestRawValue(packet_type, parameter_type,
                   identifier, apid, data_mode, 
                   &num_samples, token,
                   &size_of_data, value, status);
 
switch (return_code)
{
    case SUCCESS:
        printf("Success!\n");
 
        for (sample=0; sample<num_samples; sample++)
        {
            printf("Sample: %d\n", sample);
            for(j=0; j<size_of_data; j++)
            {
                sprintf((char *)hex_pattern, "%.2x ",value[sample][j]); 
                printf("%s", hex_pattern);
            }
 
            printf("\n");
            printf("Status: %s\n", status[sample]);
        }
        break;
 
    case API_TOO_MANY_SAMPLES:
        printf("Too Many Samples!\n");
 
        // Print out the samples that were available.
        for (sample=0; sample<num_samples; sample++)
        {
            printf("Sample: %d\n", sample);
            for(j=0; j<size_of_data; j++)
            {
                sprintf((char *)hex_pattern, "%.2x ",value[sample][j]); 
                printf("%s", hex_pattern);
            }
            printf("\n");
            printf("Status: %s\n", status[sample]);
        }
        break;
 
    default:
        printf("Error %d\n", return_code);
        break;
}
 
// Delete 2D Data Array.
for (sample=0; sample< num_samp_allocated; sample++)
    free(value[sample]);
free(value);
 
// Delete Status String 2D Array.
for (sample=0; sample< num_samp_allocated; sample++)
    free(status[sample]);
free(status);

Longer examples that include this method:
None

GetNextCalibratedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextCalibratedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when calibrated is a floating point.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the double integer values.
value = (double *)malloc(sizeof(double)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNextCalibratedDoubleValue( PDSS_PAYLOAD, "MSID106", "7", REAL_TIME, &num_samples, SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %lf.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextCalibratedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextCalibratedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	size_of_data,
		char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when calibrated is a string.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char **value;
unsigned int ii;
long size_of_data;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
unsigned long sample;
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the string values.
//Create the 2D Array to hold the status strings for each sample. 
value = (char **)malloc(sizeof(char **)*num_samples);
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    value[sample] = (char *)malloc(100);        // assume 100 character max (including NULL)
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
size_of_data = 100;
ret_value = GetNextCalibratedStringValue( PDSS_PAYLOAD, "MSID079", "7", REAL_TIME, &num_samples, LES_SENSE, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %s.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextConvertedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextConvertedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is a floating point.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the double values.
value = (double *)malloc(sizeof(double)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNextConvertedDoubleValue( PDSS_PAYLOAD, "MSID106", "7", REAL_TIME, &num_samples, NO_SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %lf.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextConvertedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextConvertedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is an integer.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the integer values.
value = (long *)malloc(sizeof(long)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNextConvertedIntegerValue( PDSS_PAYLOAD, "MSID107", "7", REAL_TIME, &num_samples, NO_SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %d.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextConvertedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextConvertedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	size_of_data,
		char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is a string.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char **value;
unsigned int ii, sample;
long size_of_data;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the string values.
//Create the 2D Array to hold the status strings for each sample. 
value = (char **)malloc(sizeof(char **)*num_samples);
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    value[sample] = (char *)malloc(100);        // assume 100 character max (including NULL)
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
size_of_data = 100;
ret_value = GetNextConvertedStringValue( PDSS_PAYLOAD, "MSID127", "7", REAL_TIME, &num_samples, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %s.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextConvertedTimeValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextConvertedTimeValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		TReK_Time *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is a time.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
TReK_Time *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the time values.
value = (TReK_Time *)malloc(sizeof(TReK_Time)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNextConvertedTimeValue( PDSS_PAYLOAD, "MSID128", "7", REAL_TIME, &num_samples, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Sample %u:  %04u-%02u-%02u %02u:%02u:%02u.  Status is %s.\n", ii, 
                            value[ii].tm_time.tm_year + 1900, 
                            value[ii].tm_time.tm_mon + 1, 
                            value[ii].tm_time.tm_mday, 
                            value[ii].tm_time.tm_hour, 
                            value[ii].tm_time.tm_min, 
                            value[ii].tm_time.tm_sec, 
                            status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextConvertedUnsignedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextConvertedUnsignedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		unsigned long *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple next sample(s) for a parameter that when converted is an unsigned integer.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned long *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
num_samples = 10;
 
// Create the array to hold the unsigned integer values.
value = (unsigned long *)malloc(sizeof(unsigned long)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetNextConvertedUnsignedIntegerValue( PDSS_PAYLOAD, "MSID108", "7", REAL_TIME, &num_samples, NO_SENSE, token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %u.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextDatazone()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextDatazone	(	int	packet_type,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		unsigned char *	value,
		char *	status
	)

Gets the next available data zone for the specified packet.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for a single sample of the data that is being returned. The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, than you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned char value[10000];
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 10000;                   // reset this before each call to function
ret_value = GetNextDatazone( PDSS_PAYLOAD, "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Size of data returned is %d.  Status is %s.\n", size_of_data, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetNextRawValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetNextRawValue	(	int	packet_type,
		int	parameter_type,
		const char *	identifier,
		const char *	apid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	size_of_data,
		unsigned char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of the next raw value for a specified parameter. A parameter can be an entire packet, a subset, or an MSID.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	parameter_type	On a TReK System, any data aggregate is considered a parameter. Therefore packets, subsets, and MSIDs are all considered parameters. The parameter type argument identifies what type of parameter is being retrieved. The parameter_type information passed in should be one of the following values: CCSDS_PACKET, EHS_PACKET, SUBSET, or MSID. Please note that when you request to retrieve a CCSDS_PACKET, the API will return a complete CCSDS packet. This does not include the EHS header. You must pass in a parameter type of EHS_PACKET to retrieve the EHS header information.
[in]	identifier	The identifier for the parameter. The identifier is based on the parameter_type and should be one of the following: Parameter Type Identifier Should Be A(n) EHS_PACKET APID MSID MSID (Parameter) CCSDS_PACKET APID EXPRESS Source Function Code UFO User Assigned ID
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters.
int packet_type;
int parameter_type;
char identifier[MSID_LEN];
char apid[APID_LEN];
int data_mode;
unsigned long num_samples;
unsigned long sample;
long token[TOKEN_SIZE];
long size_of_data;
unsigned char **value;
unsigned char hex_pattern[DATA_LEN];
char **status;
int return_code;
int i;
long j;
unsigned long num_samp_allocated;
 
// Initialize or Assign Values to Input Parameters.
packet_type = PDSS_PAYLOAD;
parameter_type = MSID;
strcpy(identifier, "MSID038");
strcpy(apid, "");
data_mode = REAL_TIME;
num_samples = 3;
size_of_data = DATA_LEN;
num_samp_allocated = num_samples;
 
// Initialize the token for the first call. For all calls
// after the first call, don’t initialize the token, just  
// pass in the token that was returned from the previous call. 
 
for (i=0; i<TOKEN_SIZE; i++)
    token[i] = 0;
 
// Create the 2D Array to hold the raw value to be returned and initialize it to zero.   
value = (unsigned char **)malloc(sizeof(unsigned char **)
              *num_samples);
 
for (sample=0; sample< num_samp_allocated; sample++)
{
    value[sample] = (unsigned char*)malloc(size_of_data);
 
    for (j=0; j<size_of_data; j++)
    {
        value[sample][j] = 0;
    }
}
 
// Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample< num_samp_allocated; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
    strcpy(status[sample], " / / ");
}
 
// Call the API function.
return_code = GetNextRawValue(packet_type, parameter_type,
                   identifier, apid, data_mode, 
                   &num_samples, token,
                   &size_of_data, value, status);
 
switch (return_code)
{
    case SUCCESS:
    case API_MORE_DATA_AVAILABLE:
        printf("Success!\n");
 
        for (sample=0; sample<num_samples; sample++)
        {
            printf("Sample: %d\n", sample);
            for(j=0; j<size_of_data; j++)
            {
                sprintf((char *)hex_pattern, "%.2x ",value[sample][j]); 
                printf("%s", hex_pattern);
            }
 
            printf("\n");
            printf("Status: %s\n", status[sample]);
        }
        break;
 
    case API_TOO_MANY_SAMPLES:
        printf("Too Many Samples!\n");
 
        // Print out the samples that were available.
        for (sample=0; sample<num_samples; sample++)
        {
            printf("Sample: %d\n", sample);
            for(j=0; j<size_of_data; j++)
            {
                sprintf((char *)hex_pattern, "%.2x ",value[sample][j]); 
                printf("%s", hex_pattern);
            }
            printf("\n");
            printf("Status: %s\n", status[sample]);
        }
        break;
 
    default:
        printf("Error %d\n", return_code);
        break;
}
 
// Delete 2D Data Array.
for (sample=0; sample< num_samp_allocated; sample++)
    free(value[sample]);
free(value);
 
// Delete Status String 2D Array.
for (sample=0; sample< num_samp_allocated; sample++)
    free(status[sample]);
free(status);

Longer examples that include this method:
None

GetOneNewestCalibratedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestCalibratedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char *	status
	)

Gets the newest available calibrated double value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNewestCalibratedDoubleValue( PDSS_PAYLOAD, "MSID009", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %lf.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestCalibratedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestCalibratedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the newest available calibrated string (enumerator) value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char value[100];                        // strings must be less than or equal to 100 characters including NULL
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 100;                     // always reset this value prior to each call.
ret_value = GetOneNewestCalibratedStringValue( PDSS_PAYLOAD, "MSID079", "7", REAL_TIME, LES_SENSE, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %s.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestConvertedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestConvertedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char *	status
	)

Gets the newest available double value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNewestConvertedDoubleValue( PDSS_PAYLOAD, "MSID106", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %lf.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestConvertedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestConvertedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	value,
		char *	status
	)

Gets the newest available integer value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestConvertedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestConvertedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the newest available string value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char value[100];                        // strings must be less than or equal to 100 characters including NULL
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 100;                     // always reset this value prior to each call.
ret_value = GetOneNewestConvertedStringValue( PDSS_PAYLOAD, "MSID001", "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %s.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestConvertedTimeStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestConvertedTimeStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the newest available time string value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char value[100];                        // strings must be less than or equal to 100 characters including NULL
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 100;                     // always reset this value prior to each call.
ret_value = GetOneNewestConvertedTimeStringValue( PDSS_PAYLOAD, "MSID128", "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %s.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestConvertedTimeValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestConvertedTimeValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		long *	token,
		TReK_Time *	value,
		char *	status
	)

Gets the newest available time value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
TReK_Time value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNewestConvertedTimeValue( PDSS_PAYLOAD, "MSID128", "7", REAL_TIME, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Time: %04u-%02u-%02u %02u:%02u:%02u.  Status is %s.\n", 
                        value.tm_time.tm_year + 1900, 
                        value.tm_time.tm_mon + 1, 
                        value.tm_time.tm_mday, 
                        value.tm_time.tm_hour, 
                        value.tm_time.tm_min, 
                        value.tm_time.tm_sec, 
                        status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestConvertedUnsignedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestConvertedUnsignedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		unsigned long *	value,
		char *	status
	)

Gets the newest available unsigned integer value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned long value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNewestConvertedUnsignedIntegerValue( PDSS_PAYLOAD, "MSID015", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %u.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNewestRawValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNewestRawValue	(	int	packet_type,
		int	parameter_type,
		const char *	identifier,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		unsigned char *	value,
		char *	status
	)

Gets the newest available raw (unprocessed/binary) value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	parameter_type	On a TReK Release 3 System, any data aggregate is considered a parameter. Therefore packets, subsets, and MSIDs are all considered parameters. The parameter type argument identifies what type of parameter is being retrieved. The parameter_type information passed in should be one of the following values: CCSDS_PACKET, EHS_PACKET, SUBSET, or MSID. Please note that when you request to retrieve a CCSDS_PACKET, the API will return a complete CCSDS packet. This does not include the EHS header. You must pass in a parameter type of EHS_PACKET to retrieve the EHS header information.
[in]	identifier	The identifier for the parameter. The identifier is based on the parameter_type and should be one of the following: Parameter Type Identifier Should Be A(n) EHS_PACKET APID MSID MSID (Parameter) CCSDS_PACKET APID EXPRESS Source Function Code UFO User Assigned ID
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for a single sample of the data that is being returned. The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, than you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned char value[10000];
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 10000;                   // reset this before each call to function
ret_value = GetOneNewestRawValue( PDSS_PAYLOAD, CCSDS_PACKET, "7", "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Size of data returned is %d.  Status is %s.\n", size_of_data, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextCalibratedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextCalibratedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char *	status
	)

Gets the next available calibrated double value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNextCalibratedDoubleValue( PDSS_PAYLOAD, "MSID009", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %lf.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextCalibratedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextCalibratedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the next available calibrated string (enumerator) value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char value[100];                        // strings must be less than or equal to 100 characters including NULL
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 100;                     // always reset this value prior to each call.
ret_value = GetOneNextCalibratedStringValue( PDSS_PAYLOAD, "MSID079", "7", REAL_TIME, LES_SENSE, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %s.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextConvertedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextConvertedDoubleValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		double *	value,
		char *	status
	)

Gets the next available double value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
double value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNextConvertedDoubleValue( PDSS_PAYLOAD, "MSID106", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %lf.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextConvertedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextConvertedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	value,
		char *	status
	)

Gets the next available integer value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNextConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextConvertedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextConvertedStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the next available string value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char value[100];                        // strings must be less than or equal to 100 characters including NULL
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 100;                     // always reset this value prior to each call.
ret_value = GetOneNextConvertedStringValue( PDSS_PAYLOAD, "MSID001", "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %s.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextConvertedTimeStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextConvertedTimeStringValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the next available time string value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
char value[100];                        // strings must be less than or equal to 100 characters including NULL
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 100;                     // always reset this value prior to each call.
ret_value = GetOneNextConvertedTimeStringValue( PDSS_PAYLOAD, "MSID128", "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %s.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextConvertedTimeValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextConvertedTimeValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		long *	token,
		TReK_Time *	value,
		char *	status
	)

Gets the next available time value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
TReK_Time value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNextConvertedTimeValue( PDSS_PAYLOAD, "MSID128", "7", REAL_TIME, token, &value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Time: %04u-%02u-%02u %02u:%02u:%02u.  Status is %s.\n", 
                        value.tm_time.tm_year + 1900, 
                        value.tm_time.tm_mon + 1, 
                        value.tm_time.tm_mday, 
                        value.tm_time.tm_hour, 
                        value.tm_time.tm_min, 
                        value.tm_time.tm_sec, 
                        status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextConvertedUnsignedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextConvertedUnsignedIntegerValue	(	int	packet_type,
		const char *	msid,
		const char *	apid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		unsigned long *	value,
		char *	status
	)

Gets the next available unsigned integer value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned long value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
ret_value = GetOneNextConvertedUnsignedIntegerValue( PDSS_PAYLOAD, "MSID015", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Value is %u.  Status is %s.\n", value, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneNextRawValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneNextRawValue	(	int	packet_type,
		int	parameter_type,
		const char *	identifier,
		const char *	apid,
		int	data_mode,
		long *	token,
		long *	size_of_data,
		unsigned char *	value,
		char *	status
	)

Gets the next available raw (unprocessed/binary) value for the specified parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	parameter_type	On a TReK Release 3 System, any data aggregate is considered a parameter. Therefore packets, subsets, and MSIDs are all considered parameters. The parameter type argument identifies what type of parameter is being retrieved. The parameter_type information passed in should be one of the following values: CCSDS_PACKET, EHS_PACKET, SUBSET, or MSID. Please note that when you request to retrieve a CCSDS_PACKET, the API will return a complete CCSDS packet. This does not include the EHS header. You must pass in a parameter type of EHS_PACKET to retrieve the EHS header information.
[in]	identifier	The identifier for the parameter. The identifier is based on the parameter_type and should be one of the following: Parameter Type Identifier Should Be A(n) EHS_PACKET APID MSID MSID (Parameter) CCSDS_PACKET APID EXPRESS Source Function Code UFO User Assigned ID
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for a single sample of the data that is being returned. The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, than you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
unsigned char value[10000];
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
 
size_of_data = 10000;                   // reset this before each call to function
ret_value = GetOneNextRawValue( PDSS_PAYLOAD, CCSDS_PACKET, "7", "7", REAL_TIME, token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.
    printf( "Size of data returned is %d.  Status is %s.\n", size_of_data, status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketCalibratedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketCalibratedDoubleValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		double *	value,
		char *	status
	)

Gets the calibrated double value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
double second_value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    ret_value = GetOneSamePacketConvertedDoubleValue( PDSS_PAYLOAD, "MSID009", REAL_TIME, NO_SENSE, second_token, token, &second_value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %lf.\n", second_value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketCalibratedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketCalibratedStringValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the calibrated string value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
long size_of_data;
char str_value[100];
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    size_of_data = 100;
    ret_value = GetOneSamePacketCalibratedStringValue( PDSS_PAYLOAD, "MSID001", REAL_TIME, NO_SENSE, second_token, token, &size_of_data, str_value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %s.\n", str_value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketConvertedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketConvertedDoubleValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		double *	value,
		char *	status
	)

Gets the double value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
double second_value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    ret_value = GetOneSamePacketConvertedDoubleValue( PDSS_PAYLOAD, "MSID106", REAL_TIME, NO_SENSE, second_token, token, &second_value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %lf.\n", second_value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketConvertedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketConvertedIntegerValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		long *	value,
		char *	status
	)

Gets the integer value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    ret_value = GetOneSamePacketConvertedIntegerValue( PDSS_PAYLOAD, "MSID009", REAL_TIME, NO_SENSE, second_token, token, &value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %d.\n", value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketConvertedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketConvertedStringValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the string value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
char second_value[1024];
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    size_of_data = 1024;
    ret_value = GetOneSamePacketConvertedStringValue( PDSS_PAYLOAD, "MSID001", REAL_TIME, second_token, token, &size_of_data, second_value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %s.\n", second_value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketConvertedTimeStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketConvertedTimeStringValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		char *	value,
		char *	status
	)

Gets the time string value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[in,out]	size_of_data	On Input, this field should indicate how much space you have allocated for the data that is being returned (i.e. how much space is available for the value parameter). If the value being returned is larger than the amount of space available, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. WARNING: If you tell the API that you have allocated enough space but you really haven’t, the API will believe you and will fill in the value parameter. Therefore, if there isn’t enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating. On Output, the API will update the size_of_data parameter to indicate the size of the data returned in the value parameter. Please note that when strings are converted all of the characters are converted based on the length specified in the database. The entire length is copied into the value parameter (not just the NULL character). .
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
long size_of_data;
char second_value[100];
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    size_of_data = 100;
    ret_value = GetOneSamePacketConvertedTimeStringValue( PDSS_PAYLOAD, "MSID128", REAL_TIME, second_token, token, &size_of_data, second_value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %s.\n", second_value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketConvertedTimeValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketConvertedTimeValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		long *	token,
		long *	from_this_pkt_token,
		TReK_Time *	value,
		char *	status
	)

Gets the time value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
TReK_Time value;
long int_value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &int_value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", int_value, status );
 
    // now get another value from the same packet
    ret_value = GetOneSamePacketConvertedTimeValue( PDSS_PAYLOAD, "MSID128", REAL_TIME, second_token, token, &value, status );
 
    if( ret_value == SUCCESS )
        printf( "Time: %04u-%02u-%02u %02u:%02u:%02u.  Status is %s.\n", 
                            value.tm_time.tm_year + 1900, 
                            value.tm_time.tm_mon + 1, 
                            value.tm_time.tm_mday, 
                            value.tm_time.tm_hour, 
                            value.tm_time.tm_min, 
                            value.tm_time.tm_sec, 
                            status );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketConvertedUnsignedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketConvertedUnsignedIntegerValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		unsigned long *	value,
		char *	status
	)

Gets the unsigned integer value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
unsigned long second_value;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    ret_value = GetOneSamePacketConvertedUnsignedIntegerValue( PDSS_PAYLOAD, "MSID009", REAL_TIME, NO_SENSE, second_token, token, &second_value, status );
 
    if( ret_value == SUCCESS )
        printf( "Value is %u.\n", second_value );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetOneSamePacketRawValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetOneSamePacketRawValue	(	int	packet_type,
		int	parameter_type,
		const char *	identifier,
		int	data_mode,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		unsigned char *	value,
		char *	status
	)

Gets the raw value for the specified parameter from the same packet as another parameter.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	parameter_type	On a TReK Release 3 System, any data aggregate is considered a parameter. Therefore packets, subsets, and MSIDs are all considered parameters. The parameter type argument identifies what type of parameter is being retrieved. The parameter_type information passed in should be one of the following values: CCSDS_PACKET, EHS_PACKET, SUBSET, or MSID. Please note that when you request to retrieve a CCSDS_PACKET, the API will return a complete CCSDS packet. This does not include the EHS header. You must pass in a parameter type of EHS_PACKET to retrieve the EHS header information.
[in]	identifier	The identifier for the parameter. The identifier is based on the parameter_type and should be one of the following: Parameter Type Identifier Should Be A(n) EHS_PACKET APID MSID MSID (Parameter) CCSDS_PACKET APID EXPRESS Source Function Code UFO User Assigned ID
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_MORE_DATA_AVAILABLE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long second_token[3];
long value;
unsigned char bin_value[100];
long size_of_data;
char status[6];                     // status string is always 6 bytes
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
second_token[0] = second_token[1] = second_token[2] = 0;
 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD, "MSID016", "7", REAL_TIME, NO_SENSE, token, &value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    printf( "Value is %d.  Status is %s.\n", value, status );
 
    // now get another value from the same packet
    size_of_data = 100;
    ret_value = GetOneSamePacketRawValue( PDSS_PAYLOAD, MSID, "MSID009", REAL_TIME, second_token, token, &size_of_data, bin_value, status );
 
    if( ret_value == SUCCESS )
        printf( "First byte value is %02x.\n", bin_value[0] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetPacketArrivalEventName()

int EXPORT_THIS_ANSI_C_FUNCTION GetPacketArrivalEventName	(	int	packet_type,
		const char *	apid,
		int	data_mode,
		char **	event_name
	)

This function gets the event name associated with packet arrival. This string can be used with the WaitForPacketArrival() function. When a packet arrives the WaitForPacketArrival() function releases and you can get new data from the packet.

Note

This is a TReK Release 3 ANSI-C compatible function. This function requires you to use a new function (WaitForPacketArrival()) that was not part of Release 3.

If you use this function to get a packet arrival event for either GSE or GSE_MERGE data, you must now include the format ID as part of the APID string input. The string should be "apid.format". For example, if the APID is 345 and the format ID is 2, then use "345.2" for the apid argument to the function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[out]	event_name	This parameter is an Output parameter. The Output will be the Packet Arrival Event Name. Memory is created to hold the Packet Arrival Event Name. No memory is allocated if return code is not SUCCESS. The User is responsible for deallocating the memory.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_INVALID_APID (Release 3 return code)

API_INVALID_DATA_MODE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters.
int return_code;
char *event_name = 0;
 
// Call the API function.
return_code = GetPacketArrivalEventName(PDSS_PAYLOAD,
                   "7", REAL_TIME, 
                   &event_name);
 
if( return_code == SUCCESS )
{
    // Have an event name, now wait on it
    return_code = WaitForPacketArrival( event_name, 5000 );
 
    if( return_code == SUCCESS )
    {
        // get data 
    }
    else
    {
        // handle error (most likely TCA_WAIT_TIMEOUT)
    }
}
 
return_code = UnregisterPacketArrivalEvent( PDSS_PAYLOAD,
                   "7", REAL_TIME, event_name );
 
if( return_code )
    printf( "Error %d.  Safe to continue.\n", return_code );
 
free( event_name );     // user must free the data

Longer examples that include this method:
None

GetParameterInformation()

int EXPORT_THIS_ANSI_C_FUNCTION GetParameterInformation	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		const char *	processing_flag,
		Measurement_Properties *	meas_prop
	)

This function provides a way to retrieve parameter information about a MSID.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The packet type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The MSID for the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	processing_flag	The processing flag. This should be one of the following: PROCESSING_FLAG_UNPROCESSED, PROCESSING_FLAG_CONVERTED, or PROCESSING_FLAG_CALIBRATED. If the packet_type is GSE, GSE_MERGE, or CDP you can pass any of the processing flags. For all other packet types you should use PROCESSING_FLAG_UNPROCESSED.
[out]	meas_prop	The measurement properties of the parameter. You must allocate memory for this structure. The Measurement_Properties struct is defined in the trek_user_api.h file.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_INVALID_DATA_MODE (Release 3 return code)

API_PARAMETER_NOT_FOUND (Release 3 return code)

Example:

int ret_value;
Measurement_Properties meas_prop;
 
ret_value = GetParameterInformation( PDSS_PAYLOAD, "MSID016", REAL_TIME, PROCESSING_FLAG_UNPROCESSED, &meas_prop );
 
if( ret_value == SUCCESS )
{
    // meas_prop has valid data
    printf( "Data type is %s\n", meas_prop.data_type );
}

Longer examples that include this method:
None

GetSamePacketCalibratedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketCalibratedDoubleValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		double *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is calibrated as a double.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
double *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
// Call a GetNewest or GetNext function 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors
if( ret_value != SUCCESS )
{
    //perform error checking 
}
 
num_samples = 10;
 
// Create the array to hold the double integer values.
value = (double *)malloc(sizeof(double)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetSamePacketCalibratedDoubleValue( PDSS_PAYLOAD, "MSID106", REAL_TIME, &num_samples, LES_SENSE, token, from_this_pkt_token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %lf.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketCalibratedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketCalibratedStringValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is calibrated as a character string.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
char **value;
unsigned int ii, sample;
long size_of_data;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
// Call a GetNewest or GetNext function 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors
if( ret_value != SUCCESS )
{
    //perform error checking 
}
 
num_samples = 10;
 
// Create the array to hold the string values.
//Create the 2D Array to hold the status strings for each sample. 
value = (char **)malloc(sizeof(char **)*num_samples);
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    value[sample] = (char *)malloc(100);        // assume 100 character max (including NULL)
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
size_of_data = 100;
ret_value = GetSamePacketCalibratedStringValue( PDSS_PAYLOAD, "MSID079", REAL_TIME, &num_samples, LES_SENSE, token, from_this_pkt_token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_MORE_DATA_AVAILABLE )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %s.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketConvertedDoubleValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketConvertedDoubleValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		double *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as a double.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
double *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
// Call a GetNewest or GetNext function 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors
if( ret_value != SUCCESS )
{
    //perform error checking 
}
 
num_samples = 10;
 
// Create the array to hold the double integer values.
value = (double *)malloc(sizeof(double)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetSamePacketConvertedDoubleValue( PDSS_PAYLOAD, "MSID106", REAL_TIME, &num_samples, NO_SENSE, token, from_this_pkt_token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %lf.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketConvertedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketConvertedIntegerValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		long *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as an integer.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
long *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
// Call a GetNewest or GetNext function
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors 
if( ret_value != SUCCESS )
{
    // perform error checking
}
 
num_samples = 10;
 
// Create the array to hold the integer values.
value = (long *)malloc(sizeof(long)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetSamePacketConvertedIntegerValue( PDSS_PAYLOAD, "MSID107", REAL_TIME, &num_samples, NO_SENSE, token, from_this_pkt_token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %d.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketConvertedStringValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketConvertedStringValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as a character string.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
char **value;
unsigned int ii, sample;
long size_of_data;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
// Call a GetNewest or GetNext function 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors
if( ret_value != SUCCESS )
{
    //perform error checking 
}
 
num_samples = 10;
 
// Create the array to hold the string values.
//Create the 2D Array to hold the status strings for each sample. 
value = (char **)malloc(sizeof(char **)*num_samples);
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    value[sample] = (char *)malloc(100);        // assume 100 character max (including NULL)
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
size_of_data = 100;
ret_value = GetSamePacketConvertedStringValue( PDSS_PAYLOAD, "MSID127", REAL_TIME, &num_samples, token, from_this_pkt_token, &size_of_data, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %s.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketConvertedTimeValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketConvertedTimeValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	from_this_pkt_token,
		TReK_Time *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as a time value. The time value is returned via a TReK_Time structure. The definition of the TReK_Time structure is located in the trek.h file. The TReK_Time structure contains a variable that is a tm_time structure. The tm_time structure is defined in the C Run-time library.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
TReK_Time *value;
unsigned int ii, sample;
unsigned long num_samples;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
// Call a GetNewest or GetNext function 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors
if( ret_value != SUCCESS )
{
    //perform error checking 
}
 
num_samples = 10;
 
// Create the array to hold the time values.
value = (TReK_Time *)malloc(sizeof(TReK_Time)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetSamePacketConvertedTimeValue( PDSS_PAYLOAD, "MSID128", REAL_TIME, &num_samples, token, from_this_pkt_token, value, status );
 
if( ret_value == SUCCESS || ret_value == API_TOO_MANY_SAMPLES )
{
    // Data is good.  If API_TOO_MANY_SAMPLES is returned, you have not
    // allocated enough space for all the data that is available.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Sample %u:  %04u-%02u-%02u %02u:%02u:%02u.  Status is %s.\n", ii, 
                            value[ii].tm_time.tm_year + 1900, 
                            value[ii].tm_time.tm_mon + 1, 
                            value[ii].tm_time.tm_mday, 
                            value[ii].tm_time.tm_hour, 
                            value[ii].tm_time.tm_min, 
                            value[ii].tm_time.tm_sec, 
                            status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketConvertedUnsignedIntegerValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketConvertedUnsignedIntegerValue	(	int	packet_type,
		const char *	msid,
		int	data_mode,
		unsigned long *	num_samples,
		int	limit_es_flag,
		long *	token,
		long *	from_this_pkt_token,
		unsigned long *	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter from the same packet as another parameter when the desired parameter is converted as an unsigned integer.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	msid	The name of the parameter.
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in]	limit_es_flag	This parameter indicates whether Limit/Expected State Sensing should be performed. The value passed in should be NO_SENSE or SENSE.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

int ret_value;
long token[3];
long from_this_pkt_token[3];
unsigned long *value;
unsigned int ii;
unsigned long num_samples;
unsigned long sample;
char **status;                      // status string is always 6 bytes
long first_value;
char first_status[STATUS_LEN];
 
token[0] = token[1] = token[2] = 0;     // token should always be initialized to 0.
from_this_pkt_token[0] = 0;
from_this_pkt_token[1] = 0;
from_this_pkt_token[2] = 0;
 
num_samples = 3;
 
// Call a GetNewest or GetNext function 
ret_value = GetOneNewestConvertedIntegerValue( PDSS_PAYLOAD,
                   "MSID039", "", REAL_TIME,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
 
// Always check return code for errors
if( ret_value != SUCCESS )
{
    // perform error checking 
}
 
// Create the array to hold the unsigned integer values.
value = (unsigned long *)malloc(sizeof(unsigned long)*num_samples);
 
//Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample<num_samples; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
}
 
ret_value = GetSamePacketConvertedUnsignedIntegerValue( PDSS_PAYLOAD, "MSID107", REAL_TIME, &num_samples, NO_SENSE, token, from_this_pkt_token, value, status );
 
if( ret_value == SUCCESS )
{
    // Data is good.
    for( ii = 0; ii < num_samples; ii++ )
        printf( "Value[%d] is %u.  Status is %s.\n", ii, value[ii], status[ii] );
}
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetSamePacketRawValue()

int EXPORT_THIS_ANSI_C_FUNCTION GetSamePacketRawValue	(	int	packet_type,
		int	parameter_type,
		const char *	identifier,
		int	data_mode,
		unsigned long *	num_samples,
		long *	token,
		long *	from_this_pkt_token,
		long *	size_of_data,
		unsigned char **	value,
		char **	status
	)

This function provides a way to retrieve one or multiple samples of a parameter as raw (unprocessed) data from the same packet as another parameter. A parameter can be an entire packet, a subset, or an MSID.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	parameter_type	On a TReK System, any data aggregate is considered a parameter. Therefore packets, subsets, and MSIDs are all considered parameters. The parameter type argument identifies what type of parameter is being retrieved. The parameter_type information passed in should be one of the following values: CCSDS_PACKET, EHS_PACKET, SUBSET, or MSID. Please note that when you request to retrieve a CCSDS_PACKET, the API will return a complete CCSDS packet. This does not include the EHS header. You must pass in a parameter type of EHS_PACKET to retrieve the EHS header information.
[in]	identifier	The identifier for the parameter. The identifier is based on the parameter_type and should be one of the following: Parameter Type Identifier Should Be A(n) EHS_PACKET APID MSID MSID (Parameter) CCSDS_PACKET APID EXPRESS Source Function Code UFO User Assigned ID
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in,out]	num_samples	The number of samples that should be returned. On Input this parameter should indicate how many samples are requested. On Output the API will update this parameter to indicate how many samples were actually returned.
[in,out]	token	The token. The token is an array of three long integers. It is used by the TReK system to determine whether the data being retrieved is new or stale. There must be a unique token for each unique parameter request. The first time the API function is called each element in the token array should be initialized to zero. The token that is returned by the API will contain updated data and should be saved. This data should not be altered in any way. For each new call after the first call, the token passed in should be the token that was returned by the previous call. Therefore, the token returned from each call should be saved so it can be passed in on the next call.
[in]	from_this_pkt_token	The token returned by a call to another TReK Telemetry API function such as GetOneNewestConvertedInteger or GetNextRawValue. This token is used by TReK to determine which packet to retrieve the parameter specified by the identifier. The from_this_pkt_token value is not changed.
[in,out]	size_of_data	This field should indicate how much space you have allocated for a single sample of the data that is being returned (the largest sample). The value parameter can be used to return one or more samples of data. The size_of_data parameter indicates how much space is available to hold one of the samples in the value parameter. If the data being returned for a single sample is larger than the amount of space available for a single sample, as indicated by the size_of_data parameter, then you have not allocated enough space. In this case the API will output an error and will not fill in the value parameter. If the return code is TLM_API_LENGTH_ERR, then this value will be reset to the amount of space required to hold the sample. WARNING: If you tell the API that you have allocated enough space but you really have not, the API will believe you and will fill in the value parameter. Therefore, if there is not enough space, the API will undoubtedly overwrite some important memory and this will eventually lead to a crash. Therefore, you need to make sure that you allocate exactly what you say you are allocating.
[out]	value	The data returned. The calling application is responsible for allocating memory to hold the data returned.
[out]	status	The status string. This indicates the status of the data returned. The calling application is responsible for allocating memory to hold the status string that is returned.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

API_TOO_MANY_SAMPLES (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters.
int packet_type;
int parameter_type;
char identifier[MSID_LEN];
char apid[APID_LEN];
int data_mode;
unsigned long num_samples;
unsigned long sample;
long token[TOKEN_SIZE];
long from_this_pkt_token[TOKEN_SIZE];
long size_of_data;
unsigned char **value;
unsigned char hex_pattern[DATA_LEN];
char **status;
int return_code;
int i;
long j;
unsigned long num_samp_allocated;
 
// Initialize or Assign Values to Input Parameters.
packet_type = PDSS_PAYLOAD;
parameter_type = MSID;
strcpy(identifier, "MSID038");
strcpy(apid, "");
data_mode = REAL_TIME;
num_samples = 10;
size_of_data = DATA_LEN;
num_samp_allocated = num_samples;
long first_value;
char first_status[STATUS_LEN];
 
// Initialize the token for the first call. For all calls
// after the first call, don’t initialize the token, just  
// pass in the token that was returned from the previous call. 
 
for (i=0; i<TOKEN_SIZE; i++)
{
    token[i] = 0;
    from_this_pkt_token[i] = 0;
}
 
// Call a GetNewest or GetNext function 
return_code = GetOneNewestConvertedIntegerValue( packet_type,
                   "MSID039", "", data_mode,
                   SENSE, from_this_pkt_token,
                   &first_value, first_status); 
 
// Always check return code for errors
if( return_code != SUCCESS )
{
    // perform error checking
}
 
// Create the 2D Array to hold the raw value to be returned and initialize it to zero.   
value = (unsigned char **)malloc(sizeof(unsigned char **)
              *num_samples);
 
for (sample=0; sample< num_samp_allocated; sample++)
{
    value[sample] = (unsigned char*)malloc(size_of_data);
 
    for (j=0; j<size_of_data; j++)
    {
        value[sample][j] = 0;
    }
}
 
// Create the 2D Array to hold the status strings for each sample. 
status = (char **)malloc(sizeof(char **)*num_samples);
for (sample=0; sample< num_samp_allocated; sample++)
{
    status[sample] = (char *)malloc(STATUS_LEN);
    strcpy(status[sample], " / / ");
}
 
// Call the API function.
return_code = GetSamePacketRawValue(packet_type, parameter_type,
                   identifier, data_mode, 
                   &num_samples, token, from_this_pkt_token,
                   &size_of_data, value, status);
 
switch (return_code)
{
    case SUCCESS:
        printf("Success!\n");
 
        for (sample=0; sample<num_samples; sample++)
        {
            printf("Sample: %d\n", sample);
            for(j=0; j<size_of_data; j++)
            {
                sprintf((char *)hex_pattern, "%.2x ",value[sample][j]); 
                printf("%s", hex_pattern);
            }
 
            printf("\n");
            printf("Status: %s\n", status[sample]);
        }
        break;
 
    case API_TOO_MANY_SAMPLES:
        printf("Too Many Samples!\n");
 
        // Print out the samples that were available.
        for (sample=0; sample<num_samples; sample++)
        {
            printf("Sample: %d\n", sample);
            for(j=0; j<size_of_data; j++)
            {
                sprintf((char *)hex_pattern, "%.2x ",value[sample][j]); 
                printf("%s", hex_pattern);
            }
            printf("\n");
            printf("Status: %s\n", status[sample]);
        }
        break;
 
    default:
        printf("Error %d\n", return_code);
        break;
}
 
// Delete 2D Data Array.
for (sample=0; sample< num_samp_allocated; sample++)
    free(value[sample]);
free(value);
 
// Delete Status String 2D Array.
for (sample=0; sample< num_samp_allocated; sample++)
    free(status[sample]);
free(status);

Longer examples that include this method:
None

InitializeMultipleParameters()

int EXPORT_THIS_ANSI_C_FUNCTION InitializeMultipleParameters	(	int	packet_type,
		int	data_mode,
		Multiple_Add_Struct *	add_struct,
		unsigned long	number_parameters
	)

This function immediately returns SUCCESS.

Note

This is a TReK Release 3 ANSI-C compatible function. It was used to set up on demand processing. Since all processing in thei version of TReK is on-demad, the function is no longer needed. It immediately returns SUCCESS to all previous written user applications to work without modification.

Parameters

[in]	packet_type	Value not used.
[in]	data_mode	Value not used.
[in]	add_struct	Value not used.
[in]	number_parameters	Value not used.

Returns

SUCCESS

SetMonitorLogFile()

int EXPORT_THIS_ANSI_C_FUNCTION SetMonitorLogFile

(

const char *

filename

)

This function sets the filename for writing monitoring messages for archival. The filename should include the full directory path. When the file is created a timestamp is appended to the name and a ".log" extension is added after the timestamp.

Note

This is a TReK Release 3 ANSI-C compatible function.

Parameters

[in]

filename

The filename for writing monitoring messages.

Returns

SUCCESS

TLM_API_NULL_POINTER

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters. 
int return_code;
 
// Set the file for logging 
return_code = SetMonitorLogFile( "c:\\my_monitor.log" );
 
if( return_code )
{
    // error handler 
}
 
// Start logging monitoring messages 
return_code = StartMonitorLogging();
 
if( return_code )
{
    // error handler 
}
 
// Turn off logging
return_code = StopMonitorLogging();
 
if( return_code )
{
    // error handler 
}

Longer examples that include this method:
None

StartMonitorLogging()

int EXPORT_THIS_ANSI_C_FUNCTION StartMonitorLogging

(

)

This function starts logging of monitoring messages. Only messages occurring after the function call will be written to the file.

Note

This is a TReK Release 3 ANSI-C compatible function.

Returns

SUCCESS

TLM_API_NULL_POINTER

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters. 
int return_code;
 
// Set the file for logging 
return_code = SetMonitorLogFile( "c:\\my_monitor.log" );
 
if( return_code )
{
    // error handler 
}
 
// Start logging monitoring messages 
return_code = StartMonitorLogging();
 
if( return_code )
{
    // error handler 
}
 
// Turn off logging
return_code = StopMonitorLogging();
 
if( return_code )
{
    // error handler 
}

Longer examples that include this method:
None

StopMonitorLogging()

int EXPORT_THIS_ANSI_C_FUNCTION StopMonitorLogging

(

)

This function stops logging of monitoring messages.

Note

This is a TReK Release 3 ANSI-C compatible function.

Returns

SUCCESS

TLM_API_NULL_POINTER

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters. 
int return_code;
 
// Set the file for logging 
return_code = SetMonitorLogFile( "c:\\my_monitor.log" );
 
if( return_code )
{
    // error handler 
}
 
// Start logging monitoring messages 
return_code = StartMonitorLogging();
 
if( return_code )
{
    // error handler 
}
 
// Turn off logging
return_code = StopMonitorLogging();
 
if( return_code )
{
    // error handler 
}

Longer examples that include this method:
None

UnregisterPacketArrivalEvent()

int EXPORT_THIS_ANSI_C_FUNCTION UnregisterPacketArrivalEvent	(	int	packet_type,
		const char *	apid,
		int	data_mode,
		const char *	event_name
	)

Removes the specified event name associated with packet arrival.

Note

This function was not a part of the TReK Release 3 API. It is provided to make transition to Release 5 easier.

Parameters

[in]	packet_type	The stream type associated with the parameter. This should be one of the following: PDSS_PAYLOAD, PDSS_CORE, GSE, GSE_MERGE, CDP, UDSM, RPSM, SCS, CCSDS, FDP, VCDU, EXPRESS, PRCU, UFO, or IMAQ_ASCII.
[in]	apid	The CCSDS application process identifier (i.e. the packet ID). If you pass in an empty string for apid, then the parameter data you have requested will be pulled from the last packet received that contains the parameter. However, if you pass in an apid instead of an empty string, the data requested will be extracted from that particular apid (packet).
[in]	data_mode	The data mode. This should be one of the following: REAL_TIME, DUMP1, DUMP2, DUMP3, PLAYBACK1, PLAYBACK2, PLAYBACK3, PLAYBACK4, PLAYBACK5, PLAYBACK6, PLAYBACK7, PLAYBACK8, PLAYBACK9, PLAYBACK10, PLAYBACK11, NONE.
[in]	event_name	The event name that is no longer needed for signalling packet arrival.

Returns

SUCCESS

API_INVALID_PACKET_TYPE (Release 3 return code)

API_INVALID_APID (Release 3 return code)

API_INVALID_DATA_MODE (Release 3 return code)

API_NOT_ENOUGH_SPACE (Release 3 return code)

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters.
int return_code;
char *event_name = 0;
 
// Call the API function.
return_code = GetPacketArrivalEventName(PDSS_PAYLOAD,
                   "7", REAL_TIME, 
                   &event_name);
 
if( return_code == SUCCESS )
{
    // Have an event name, now wait on it
    return_code = WaitForPacketArrival( event_name, 5000 );
 
    if( return_code == SUCCESS )
    {
        // get data 
    }
    else
    {
        // handle error (most likely TCA_WAIT_TIMEOUT)
    }
}
 
return_code = UnregisterPacketArrivalEvent( PDSS_PAYLOAD,
                   "7", REAL_TIME, event_name );
 
if( return_code )
    printf( "Error %d.  Safe to continue.\n", return_code );
 
free( event_name );     // user must free the data

Longer examples that include this method:
None

WaitForPacketArrival()

int EXPORT_THIS_ANSI_C_FUNCTION WaitForPacketArrival	(	const char *	event_name,
		unsigned int	timeout
	)

This function waits for the event name retunred from the WaitForPacketArrival() function. When a packet arrives function returns and you can get new data from the packet.

Note

This function was not a part of the TReK Release 3 API. It is provided to make transition to Release 5 easier.

Parameters

[in]	event_name	The name of the event to wait for. Returned by GetPacketArrivalEventName().
[in]	timeout	The amount of time to wait for the event in milliseonds. A value of 0 will be an infinite wait.

Returns

SUCCESS

TLM_API_INIT_FAILED

TLM_API_TLS_NULL

TCA_API_NOT_CONNECTED

TLM_API_PKT_NAME_LEN_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_DATA_STORE_WAIT_ERR

TLM_API_LENGTH_ERR

TCA_WAIT_TIMEOUT

Example:

// Don’t forget to include the following header files.
#include "trek.h"
#include "trek_error.h"
#include "trek_user_api.h"
 
// Define Input Parameters.
int return_code;
char *event_name = 0;
 
// Call the API function.
return_code = GetPacketArrivalEventName(PDSS_PAYLOAD,
                   "7", REAL_TIME, 
                   &event_name);
 
if( return_code == SUCCESS )
{
    // Have an event name, now wait on it
    return_code = WaitForPacketArrival( event_name, 5000 );
 
    if( return_code == SUCCESS )
    {
        // get data 
    }
    else
    {
        // handle error (most likely TCA_WAIT_TIMEOUT)
    }
}
 
return_code = UnregisterPacketArrivalEvent( PDSS_PAYLOAD,
                   "7", REAL_TIME, event_name );
 
if( return_code )
    printf( "Error %d.  Safe to continue.\n", return_code );
 
free( event_name );     // user must free the data

Longer examples that include this method:
None