SDDS.h File Reference

Detailed Description

SDDS (Self Describing Data Set) Data Types Definitions and Function Prototypes.

This header file defines the data types, macros, structures, and function prototypes used for handling SDDS files. SDDS is a file protocol designed to store and transfer scientific data efficiently.

Copyright

• (c) 2002 The University of Chicago, as Operator of Argonne National Laboratory.
• (c) 2002 The Regents of the University of California, as Operator of Los Alamos National Laboratory.

License This file is distributed under the terms of the Software License Agreement

found in the file LICENSE included with this distribution.

Authors

M. Borland, C. Saunders, R. Soliday, H. Shang

Definition in file SDDS.h.

#include <stdio.h>
#include <stdarg.h>
#include <stdlib.h>
#include "SDDStypes.h"
#include <inttypes.h>
#include <lzma.h>

Go to the source code of this file.

Typedefs
typedef void *	voidp
typedef voidp	gzFile
typedef SDDS_DATASET	SDDS_TABLE

Functions
epicsShareFuncSDDS int	SDDS_CompareIndexedNames (const void *s1, const void *s2)
	Compares two SORTED_INDEX structures by their name fields.
epicsShareFuncSDDS int	SDDS_CompareIndexedNamesPtr (const void *s1, const void *s2)
	Compares two pointers to SORTED_INDEX structures by their name fields.
epicsShareFuncSDDS int32_t	SDDS_InitializeOutput (SDDS_DATASET *SDDS_dataset, int32_t data_mode, int32_t lines_per_row, const char *description, const char *contents, const char *filename)
	Initializes the SDDS output dataset.
epicsShareFuncSDDS int32_t	SDDS_Parallel_InitializeOutput (SDDS_DATASET *SDDS_dataset, const char *description, const char *contents, const char *filename)
	Initializes the SDDS output dataset for parallel processing.
epicsShareFuncSDDS int32_t	SDDS_InitializeAppend (SDDS_DATASET *SDDS_dataset, const char *filename)
	Initializes the SDDS dataset for appending data by adding a new page to an existing file.
epicsShareFuncSDDS int32_t	SDDS_InitializeAppendToPage (SDDS_DATASET *SDDS_dataset, const char *filename, int64_t updateInterval, int64_t *rowsPresentReturn)
	Initializes the SDDS dataset for appending data to the last page of an existing file.
epicsShareFuncSDDS int32_t	SDDS_DisconnectFile (SDDS_DATASET *SDDS_dataset)
	Disconnects the SDDS dataset from its associated file.
epicsShareFuncSDDS int32_t	SDDS_ReconnectFile (SDDS_DATASET *SDDS_dataset)
	Reconnects the SDDS dataset to its previously associated file.
epicsShareFuncSDDS long	SDDS_DisconnectInputFile (SDDS_DATASET *SDDS_dataset)
	Disconnects the input file from the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ReconnectInputFile (SDDS_DATASET *SDDS_dataset, long position)
	Reconnects the input file for the SDDS dataset at a specified position.
epicsShareFuncSDDS int32_t	SDDS_ReadNewBinaryRows (SDDS_DATASET *SDDS_dataset)
	Reads new binary rows from the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_FreeStringData (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_Terminate (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS void	SDDS_SetTerminateMode (uint32_t mode)
epicsShareFuncSDDS void	SDDS_SetColumnMemoryMode (SDDS_DATASET *SDDS_dataset, uint32_t mode)
epicsShareFuncSDDS int32_t	SDDS_GetColumnMemoryMode (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_SetRowCountMode (SDDS_DATASET *SDDS_dataset, uint32_t mode)
	Sets the row count mode for the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetAutoReadRecovery (SDDS_DATASET *SDDS_dataset, uint32_t mode)
epicsShareFuncSDDS int32_t	SDDS_UpdateRowCount (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS void	SDDS_DisableFSync (SDDS_DATASET *SDDS_dataset)
	Disables file synchronization for the SDDS dataset.
epicsShareFuncSDDS void	SDDS_EnableFSync (SDDS_DATASET *SDDS_dataset)
	Enables file synchronization for the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DoFSync (SDDS_DATASET *SDDS_dataset)
	Synchronizes the SDDS dataset's file to disk.
epicsShareFuncSDDS void	SDDS_SetLZMACompressionLevel (int32_t level)
epicsShareFuncSDDS int32_t	SDDS_GetLZMACompressionLevel (void)
epicsShareFuncSDDS int32_t	SDDS_DefineParameter (SDDS_DATASET *SDDS_dataset, const char *name, const char *symbol, const char *units, const char *description, const char *format_string, int32_t type, char *fixed_value)
	Defines a data parameter with a fixed string value.
epicsShareFuncSDDS int32_t	SDDS_DefineParameter1 (SDDS_DATASET *SDDS_dataset, const char *name, const char *symbol, const char *units, const char *description, const char *format_string, int32_t type, void *fixed_value)
	Defines a data parameter with a fixed numerical value.
epicsShareFuncSDDS int32_t	SDDS_DefineColumn (SDDS_DATASET *SDDS_dataset, const char *name, const char *symbol, const char *units, const char *description, const char *format_string, int32_t type, int32_t field_length)
	Defines a data column within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineArray (SDDS_DATASET *SDDS_dataset, const char *name, const char *symbol, const char *units, const char *description, const char *format_string, int32_t type, int32_t field_length, int32_t dimensions, const char *group_name)
	Defines a data array within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineAssociate (SDDS_DATASET *SDDS_dataset, const char *name, const char *filename, const char *path, const char *description, const char *contents, int32_t sdds)
	Defines an associate for the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_IsValidName (const char *name, const char *dataClass)
	Checks if a given name is valid for a specified class within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetNameValidityFlags (uint32_t flags)
	Sets the validity flags for parameter and column names in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineSimpleColumn (SDDS_DATASET *SDDS_dataset, const char *name, const char *unit, int32_t type)
	Defines a simple data column within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineSimpleParameter (SDDS_DATASET *SDDS_dataset, const char *name, const char *unit, int32_t type)
	Defines a simple data parameter within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineSimpleColumns (SDDS_DATASET *SDDS_dataset, int32_t number, char **name, char **unit, int32_t type)
	Defines multiple simple data columns of the same data type within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineSimpleParameters (SDDS_DATASET *SDDS_dataset, int32_t number, char **name, char **unit, int32_t type)
	Defines multiple simple data parameters of the same data type within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetNoRowCounts (SDDS_DATASET *SDDS_dataset, int32_t value)
	Sets the flag to enable or disable row counts in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_WriteLayout (SDDS_DATASET *SDDS_dataset)
	Writes the SDDS layout header to the output file.
epicsShareFuncSDDS int32_t	SDDS_EraseData (SDDS_DATASET *SDDS_dataset)
	Erases all data entries in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ProcessColumnString (SDDS_DATASET *SDDS_dataset, char *string, int32_t mode)
	Process a column definition string.
epicsShareFuncSDDS int32_t	SDDS_ProcessParameterString (SDDS_DATASET *SDDS_dataset, char *string, int32_t mode)
	Process a parameter definition string.
epicsShareFuncSDDS int32_t	SDDS_ProcessArrayString (SDDS_DATASET *SDDS_dataset, char *string)
	Process an array definition string.
epicsShareFuncSDDS int32_t	SDDS_ProcessAssociateString (SDDS_DATASET *SDDS_dataset, char *string)
	Process an associate definition string.
epicsShareFuncSDDS int32_t	SDDS_InitializeCopy (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source, char *filename, char *filemode)
epicsShareFuncSDDS int32_t	SDDS_CopyLayout (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_AppendLayout (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source, uint32_t mode)
epicsShareFuncSDDS int32_t	SDDS_CopyPage (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_CopyParameters (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_CopyArrays (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_CopyColumns (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_CopyRowsOfInterest (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_CopyRow (SDDS_DATASET *SDDS_target, int64_t target_row, SDDS_DATASET *SDDS_source, int64_t source_srow)
epicsShareFuncSDDS int32_t	SDDS_CopyRowDirect (SDDS_DATASET *SDDS_target, int64_t target_row, SDDS_DATASET *SDDS_source, int64_t source_row)
epicsShareFuncSDDS int32_t	SDDS_CopyAdditionalRows (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source)
epicsShareFuncSDDS int32_t	SDDS_CopyRows (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source, int64_t firstRow, int64_t lastRow)
epicsShareFuncSDDS void	SDDS_DeferSavingLayout (SDDS_DATASET *SDDS_dataset, int32_t mode)
epicsShareFuncSDDS int32_t	SDDS_SaveLayout (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_RestoreLayout (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_StartPage (SDDS_DATASET *SDDS_dataset, int64_t expected_n_rows)
epicsShareFuncSDDS int32_t	SDDS_ClearPage (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_LengthenTable (SDDS_DATASET *SDDS_dataset, int64_t n_additional_rows)
epicsShareFuncSDDS int32_t	SDDS_ShortenTable (SDDS_DATASET *SDDS_dataset, int64_t rows)
epicsShareFuncSDDS int32_t	SDDS_SetParameters (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
epicsShareFuncSDDS int32_t	SDDS_SetParameter (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
epicsShareFuncSDDS int32_t	SDDS_SetRowValues (SDDS_DATASET *SDDS_dataset, int32_t mode, int64_t row,...)
epicsShareFuncSDDS int32_t	SDDS_WritePage (SDDS_DATASET *SDDS_dataset)
	Writes the current data table to the output file.
epicsShareFuncSDDS int32_t	SDDS_UpdatePage (SDDS_DATASET *SDDS_dataset, uint32_t mode)
	Updates the current page of the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SyncDataSet (SDDS_DATASET *SDDS_dataset)
	Synchronizes the SDDS dataset with the disk by flushing buffered data.
epicsShareFuncSDDS int32_t	SDDS_SetColumn (SDDS_DATASET *SDDS_dataset, int32_t mode, void *data, int64_t rows,...)
	Sets the values for one data column in the current data table of an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetColumnFromDoubles (SDDS_DATASET *SDDS_dataset, int32_t mode, double *data, int64_t rows,...)
	Sets the values for a single data column using double-precision floating-point numbers.
epicsShareFuncSDDS int32_t	SDDS_SetColumnFromFloats (SDDS_DATASET *SDDS_dataset, int32_t mode, float *data, int64_t rows,...)
	Sets the values for a single data column using single-precision floating-point numbers.
epicsShareFuncSDDS int32_t	SDDS_SetColumnFromLongs (SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t *data, int64_t rows,...)
	Sets the values for a single data column using long integer numbers.
epicsShareFuncSDDS int32_t	SDDS_SetParametersFromDoubles (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
epicsShareFuncSDDS int32_t	SDDS_GetColumnInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Retrieves information about a specified column in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetParameterInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Retrieves information about a specified parameter in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetArrayInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Retrieves information about a specified array in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetAssociateInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Retrieves information about a specified associate in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ChangeColumnInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Modifies a specific field in a column definition within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ChangeParameterInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Modifies a specific field in a parameter definition within the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ChangeArrayInformation (SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode,...)
	Modifies a specific field in an array definition within the SDDS dataset.
epicsShareFuncSDDS void	SDDS_SetReadRecoveryMode (SDDS_DATASET *SDDS_dataset, int32_t mode)
	Sets the read recovery mode for an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetDefaultIOBufferSize (int32_t bufferSize)
epicsShareFuncSDDS int32_t	SDDS_InitializeInputFromSearchPath (SDDS_DATASET *SDDSin, char *file)
epicsShareFuncSDDS int32_t	SDDS_InitializeInput (SDDS_DATASET *SDDS_dataset, char *filename)
epicsShareFuncSDDS int32_t	SDDS_ReadLayout (SDDS_DATASET *SDDS_dataset, FILE *fp)
epicsShareFuncSDDS int32_t	SDDS_InitializeHeaderlessInput (SDDS_DATASET *SDDS_dataset, char *filename)
	Initializes the SDDS dataset for headerless input.
epicsShareFuncSDDS int64_t	SDDS_GetRowLimit ()
epicsShareFuncSDDS int64_t	SDDS_SetRowLimit (int64_t limit)
epicsShareFuncSDDS int32_t	SDDS_GotoPage (SDDS_DATASET *SDDS_dataset, int32_t page_number)
	Sets the current page of the SDDS dataset to the specified page number.
epicsShareFuncSDDS int32_t	SDDS_CheckEndOfFile (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_ReadPage (SDDS_DATASET *SDDS_dataset)
epicsShareFuncSDDS int32_t	SDDS_ReadPageSparse (SDDS_DATASET *SDDS_dataset, uint32_t mode, int64_t sparse_interval, int64_t sparse_offset, int32_t sparse_statistics)
epicsShareFuncSDDS int32_t	SDDS_ReadPageLastRows (SDDS_DATASET *SDDS_dataset, int64_t last_rows)
epicsShareFuncSDDS int32_t	SDDS_ReadAsciiPage (SDDS_DATASET *SDDS_dataset, int64_t sparse_interval, int64_t sparse_offset, int32_t sparse_statistics)
	Reads the next SDDS ASCII page into memory with optional data sparsity and statistics.
epicsShareFuncSDDS int32_t	SDDS_ReadRecoveryPossible (SDDS_DATASET *SDDS_dataset)
	Checks if any data in an SDDS page was recovered after an error was detected.
epicsShareFuncSDDS int32_t	SDDS_SetColumnFlags (SDDS_DATASET *SDDS_dataset, int32_t column_flag_value)
	Sets the acceptance flags for all columns in the current data table of a data set.
epicsShareFuncSDDS int32_t	SDDS_SetRowFlags (SDDS_DATASET *SDDS_dataset, int32_t row_flag_value)
	Sets the acceptance flags for all rows in the current data table of a data set.
epicsShareFuncSDDS int32_t	SDDS_GetRowFlag (SDDS_DATASET *SDDS_dataset, int64_t row)
	Retrieves the acceptance flag of a specific row in the current data table.
epicsShareFuncSDDS int32_t	SDDS_GetRowFlags (SDDS_DATASET *SDDS_dataset, int32_t *flag, int64_t rows)
	Retrieves the acceptance flags for all rows in the current data table.
epicsShareFuncSDDS int32_t	SDDS_BufferedRead (void *target, int64_t targetSize, FILE *fp, SDDS_FILEBUFFER *fBuffer, int32_t type, int32_t byteOrder)
epicsShareFuncSDDS int32_t	SDDS_AssertRowFlags (SDDS_DATASET *SDDS_dataset, uint32_t mode,...)
	Sets acceptance flags for rows based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_MatchColumns (SDDS_DATASET *SDDS_dataset, char ***match, int32_t matchMode, int32_t typeMode,...)
	Matches and retrieves column names from an SDDS dataset based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_MatchParameters (SDDS_DATASET *SDDS_dataset, char ***match, int32_t matchMode, int32_t typeMode,...)
	Matches and retrieves parameter names from an SDDS dataset based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_MatchArrays (SDDS_DATASET *SDDS_dataset, char ***match, int32_t matchMode, int32_t typeMode,...)
	Matches and retrieves array names from an SDDS dataset based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_Logic (int32_t previous, int32_t match, uint32_t logic)
	Applies logical operations to determine the new state of a row flag based on previous and current match conditions.
epicsShareFuncSDDS int32_t	SDDS_SetColumnsOfInterest (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Sets the acceptance flags for columns based on specified naming criteria.
epicsShareFuncSDDS int32_t	SDDS_AssertColumnFlags (SDDS_DATASET *SDDS_dataset, uint32_t mode,...)
	Sets acceptance flags for columns based on specified criteria.
epicsShareFuncSDDS int64_t	SDDS_SetRowsOfInterest (SDDS_DATASET *SDDS_dataset, char *selection_column, int32_t mode,...)
	Sets the rows of interest in an SDDS dataset based on various selection criteria.
epicsShareFuncSDDS int64_t	SDDS_MatchRowsOfInterest (SDDS_DATASET *SDDS_dataset, char *selection_column, char *label_to_match, int32_t logic)
	Matches and marks rows of interest in an SDDS dataset based on label matching.
epicsShareFuncSDDS int32_t	SDDS_DeleteColumn (SDDS_DATASET *SDDS_dataset, char *column_name)
	Deletes a specified column from an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DeleteParameter (SDDS_DATASET *SDDS_dataset, char *parameter_name)
	Deletes a specified parameter from an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DeleteUnsetColumns (SDDS_DATASET *SDDS_dataset)
	Deletes all columns from an SDDS dataset that are not marked as "of interest".
epicsShareFuncSDDS int32_t	SDDS_CountColumnsOfInterest (SDDS_DATASET *SDDS_dataset)
	Counts the number of columns marked as "of interest" in the current data table.
epicsShareFuncSDDS int32_t	SDDS_ColumnIsOfInterest (SDDS_DATASET *SDDS_dataset, char *name)
	Determines if a specified column is marked as of interest in the dataset.
epicsShareFuncSDDS int32_t	SDDS_ColumnCount (SDDS_DATASET *dataset)
	Retrieves the number of columns in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ParameterCount (SDDS_DATASET *dataset)
	Retrieves the number of parameters in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ArrayCount (SDDS_DATASET *dataset)
	Retrieves the number of arrays in the SDDS dataset.
epicsShareFuncSDDS int64_t	SDDS_CountRowsOfInterest (SDDS_DATASET *SDDS_dataset)
	Counts the number of rows marked as "of interest" in the current data table.
epicsShareFuncSDDS int32_t	SDDS_DeleteUnsetRows (SDDS_DATASET *SDDS_dataset)
	Deletes rows from an SDDS dataset that are not marked as "of interest".
epicsShareFuncSDDS int64_t	SDDS_FilterRowsOfInterest (SDDS_DATASET *SDDS_dataset, char *filter_column, double lower, double upper, int32_t logic)
	Filters rows of interest in an SDDS dataset based on numeric ranges in a specified column.
epicsShareFuncSDDS int32_t	SDDS_ItemInsideWindow (void *data, int64_t index, int32_t type, double lower_limit, double upper_limit)
	Checks whether a data item is within a specified numeric window.
epicsShareFuncSDDS int64_t	SDDS_FilterRowsByNumScan (SDDS_DATASET *SDDS_dataset, char *filter_column, uint32_t mode)
	Filters rows of interest in an SDDS dataset based on numeric scanning of a specified column.
epicsShareFuncSDDS void *	SDDS_GetColumn (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves a copy of the data for a specified column, including only rows marked as "of interest".
epicsShareFuncSDDS void *	SDDS_GetInternalColumn (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves an internal pointer to the data of a specified column, including all rows.
epicsShareFuncSDDS double *	SDDS_GetColumnInDoubles (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves the data of a specified numerical column as an array of doubles, considering only rows marked as "of interest".
epicsShareFuncSDDS float *	SDDS_GetColumnInFloats (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves the data of a specified numerical column as an array of floats, considering only rows marked as "of interest".
epicsShareFuncSDDS int32_t *	SDDS_GetColumnInLong (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves the data of a specified numerical column as an array of 32-bit integers, considering only rows marked as "of interest".
epicsShareFuncSDDS short *	SDDS_GetColumnInShort (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves the data of a specified numerical column as an array of short integers, considering only rows marked as "of interest".
epicsShareFuncSDDS char **	SDDS_GetColumnInString (SDDS_DATASET *SDDS_dataset, char *column_name)
	Retrieves the data of a specified column as an array of strings, considering only rows marked as "of interest".
epicsShareFuncSDDS void *	SDDS_GetNumericColumn (SDDS_DATASET *SDDS_dataset, char *column_name, int32_t desiredType)
	Retrieves the data of a specified numerical column as an array of a desired numerical type, considering only rows marked as "of interest".
epicsShareFuncSDDS void *	SDDS_GetRow (SDDS_DATASET *SDDS_dataset, int64_t srow_index, void *memory)
	Retrieves the data of a specific selected row as an array, considering only columns marked as "of interest".
epicsShareFuncSDDS void *	SDDS_GetValue (SDDS_DATASET *SDDS_dataset, char *column_name, int64_t srow_index, void *memory)
	Retrieves the value from a specified column and selected row, optionally storing it in provided memory.
epicsShareFuncSDDS double	SDDS_GetValueAsDouble (SDDS_DATASET *SDDS_dataset, char *column_name, int64_t srow_index)
	Retrieves the value from a specified column and selected row, casting it to a double.
epicsShareFuncSDDS double	SDDS_GetValueByIndexAsDouble (SDDS_DATASET *SDDS_dataset, int32_t column_index, int64_t srow_index)
	Retrieves the value from a specified column and selected row, casting it to a double.
epicsShareFuncSDDS void *	SDDS_GetValueByIndex (SDDS_DATASET *SDDS_dataset, int32_t column_index, int64_t srow_index, void *memory)
	Retrieves the value from a specified column and selected row, optionally storing it in provided memory.
epicsShareFuncSDDS void *	SDDS_GetValueByAbsIndex (SDDS_DATASET *SDDS_dataset, int32_t column_index, int64_t srow_index, void *memory)
	Retrieves the value from a specified column and absolute row index, optionally storing it in provided memory.
epicsShareFuncSDDS void *	SDDS_GetParameter (SDDS_DATASET *SDDS_dataset, char *parameter_name, void *memory)
	Retrieves the value of a specified parameter from the current data table of a data set.
epicsShareFuncSDDS void *	SDDS_GetParameterByIndex (SDDS_DATASET *SDDS_dataset, int32_t index, void *memory)
	Retrieves the value of a specified parameter by its index from the current data table of a data set.
epicsShareFuncSDDS long double *	SDDS_GetParameterAsLongDouble (SDDS_DATASET *SDDS_dataset, char *parameter_name, long double *data)
	Retrieves the value of a specified parameter as a long double from the current data table of an SDDS dataset.
epicsShareFuncSDDS double *	SDDS_GetParameterAsDouble (SDDS_DATASET *SDDS_dataset, char *parameter_name, double *data)
	Retrieves the value of a specified parameter as a double from the current data table of an SDDS dataset.
epicsShareFuncSDDS int32_t *	SDDS_GetParameterAsLong (SDDS_DATASET *SDDS_dataset, char *parameter_name, int32_t *data)
	Retrieves the value of a specified parameter as a 32-bit integer from the current data table of a data set.
epicsShareFuncSDDS int64_t *	SDDS_GetParameterAsLong64 (SDDS_DATASET *SDDS_dataset, char *parameter_name, int64_t *data)
	Retrieves the value of a specified parameter as a 64-bit integer from the current data table of an SDDS dataset.
epicsShareFuncSDDS char *	SDDS_GetParameterAsString (SDDS_DATASET *SDDS_dataset, char *parameter_name, char **memory)
	Retrieves the value of a specified parameter as a string from the current data table of an SDDS dataset.
epicsShareFuncSDDS char *	SDDS_GetParameterAsFormattedString (SDDS_DATASET *SDDS_dataset, char *parameter_name, char **memory, char *suppliedformat)
	Retrieves the value of a specified parameter as a formatted string from the current data table of an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetParameters (SDDS_DATASET *SDDS_dataset,...)
	Retrieves multiple parameter values from the current data table of a data set.
epicsShareFuncSDDS void *	SDDS_GetFixedValueParameter (SDDS_DATASET *SDDS_dataset, char *parameter_name, void *memory)
	Retrieves the fixed value of a specified parameter from an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetDescription (SDDS_DATASET *SDDS_dataset, char **text, char **contents)
	Retrieves the text and contents descriptions from an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetArrayUnitsConversion (SDDS_DATASET *SDDS_dataset, char *column_name, char *new_units, char *old_units, double factor)
	Sets unit conversions for a specified array in an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetColumnUnitsConversion (SDDS_DATASET *SDDS_dataset, char *column_name, char *new_units, char *old_units, double factor)
	Sets unit conversions for a specified column in an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetParameterUnitsConversion (SDDS_DATASET *SDDS_dataset, char *column_name, char *new_units, char *old_units, double factor)
	Sets unit conversions for a specified parameter in an SDDS dataset.
epicsShareFuncSDDS void *	SDDS_GetMatrixOfRows (SDDS_DATASET *SDDS_dataset, int64_t *n_rows)
	Retrieves all rows marked as "of interest" as a matrix (array of row arrays).
epicsShareFuncSDDS void *	SDDS_GetCastMatrixOfRows (SDDS_DATASET *SDDS_dataset, int64_t *n_rows, int32_t sddsType)
	Retrieves all rows marked as "of interest" as a matrix, casting each value to a specified numerical type.
epicsShareFuncSDDS void *	SDDS_GetMatrixFromColumn (SDDS_DATASET *SDDS_dataset, char *column_name, int64_t dimension1, int64_t dimension2, int32_t mode)
	Extracts a matrix from a specified column in the current data table of an SDDS dataset.
epicsShareFuncSDDS void *	SDDS_GetDoubleMatrixFromColumn (SDDS_DATASET *SDDS_dataset, char *column_name, int64_t dimension1, int64_t dimension2, int32_t mode)
	Extracts a matrix of doubles from a specified column in the current data table of an SDDS dataset.
epicsShareFuncSDDS SDDS_ARRAY *	SDDS_GetArray (SDDS_DATASET *SDDS_dataset, char *array_name, SDDS_ARRAY *memory)
	Retrieves an array from the current data table of an SDDS dataset.
epicsShareFuncSDDS double *	SDDS_GetArrayInDoubles (SDDS_DATASET *SDDS_dataset, char *array_name, int32_t *values)
	Retrieves an array from the current data table of an SDDS dataset and converts its elements to doubles.
epicsShareFuncSDDS int32_t *	SDDS_GetArrayInLong (SDDS_DATASET *SDDS_dataset, char *array_name, int32_t *values)
	Retrieves an array from the current data table of an SDDS dataset and converts its elements to 32-bit integers.
epicsShareFuncSDDS char **	SDDS_GetArrayInString (SDDS_DATASET *SDDS_dataset, char *array_name, int32_t *values)
	Retrieves an array from the current data table of an SDDS dataset and converts its elements to strings.
epicsShareFuncSDDS int32_t	SDDS_SetArrayVararg (SDDS_DATASET *SDDS_dataset, char *array_name, int32_t mode, void *data_pointer,...)
	Sets the values of an array variable in the SDDS dataset using variable arguments for dimensions.
epicsShareFuncSDDS int32_t	SDDS_SetArray (SDDS_DATASET *SDDS_dataset, char *array_name, int32_t mode, void *data_pointer, int32_t *dimension)
	Sets the values of an array variable in the SDDS dataset using specified dimensions.
epicsShareFuncSDDS int32_t	SDDS_AppendToArrayVararg (SDDS_DATASET *SDDS_dataset, char *array_name, int32_t mode, void *data_pointer, int32_t elements,...)
	Appends data to an existing array variable in the SDDS dataset using variable arguments for dimensions.
epicsShareFuncSDDS void *	SDDS_Realloc (void *old_ptr, size_t new_size)
	Reallocates memory to a new size.
epicsShareFuncSDDS void *	SDDS_Malloc (size_t size)
	Allocates memory of a specified size.
epicsShareFuncSDDS void	SDDS_Free (void *mem)
	Free memory previously allocated by SDDS_Malloc.
epicsShareFuncSDDS void *	SDDS_Calloc (size_t nelem, size_t elem_size)
	Allocates zero-initialized memory for an array of elements.
epicsShareFuncSDDS int32_t	SDDS_NumberOfErrors (void)
	Retrieves the number of errors recorded by SDDS library routines.
epicsShareFuncSDDS void	SDDS_ClearErrors (void)
	Clears all recorded error messages from the SDDS error stack.
epicsShareFuncSDDS void	SDDS_SetError (char *error_text)
	Records an error message in the SDDS error stack.
epicsShareFuncSDDS void	SDDS_SetError0 (char *error_text)
	Internal function to record an error message in the SDDS error stack.
epicsShareFuncSDDS void	SDDS_Bomb (char *message)
	Terminates the program after printing an error message and recorded errors.
epicsShareFuncSDDS void	SDDS_Warning (char *message)
	Prints a warning message to stderr.
epicsShareFuncSDDS void	SDDS_RegisterProgramName (const char *name)
	Registers the executable program name for use in error messages.
epicsShareFuncSDDS void	SDDS_PrintErrors (FILE *fp, int32_t mode)
	Prints recorded error messages to a specified file stream.
epicsShareFuncSDDS char **	SDDS_GetErrorMessages (int32_t *number, int32_t mode)
	Retrieves recorded error messages from the SDDS error stack.
epicsShareFuncSDDS char **	SDDS_GetColumnNames (SDDS_DATASET *SDDS_dataset, int32_t *number)
	Retrieves the names of all columns in the SDDS dataset.
epicsShareFuncSDDS char **	SDDS_GetParameterNames (SDDS_DATASET *SDDS_dataset, int32_t *number)
	Retrieves the names of all parameters in the SDDS dataset.
epicsShareFuncSDDS char **	SDDS_GetAssociateNames (SDDS_DATASET *SDDS_dataset, int32_t *number)
	Retrieves the names of all associates in the SDDS dataset.
epicsShareFuncSDDS char **	SDDS_GetArrayNames (SDDS_DATASET *SDDS_dataset, int32_t *number)
	Retrieves the names of all arrays in the SDDS dataset.
epicsShareFuncSDDS COLUMN_DEFINITION *	SDDS_GetColumnDefinition (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the definition of a specified column from the SDDS dataset.
epicsShareFuncSDDS COLUMN_DEFINITION *	SDDS_CopyColumnDefinition (COLUMN_DEFINITION **target, COLUMN_DEFINITION *source)
	Creates a copy of a column definition.
epicsShareFuncSDDS int32_t	SDDS_FreeColumnDefinition (COLUMN_DEFINITION *source)
	Frees memory allocated for a column definition.
epicsShareFuncSDDS int32_t	SDDS_TransferColumnDefinition (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Transfers a column definition from a source dataset to a target dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineColumnLikeParameter (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Defines a column in the target dataset based on a parameter definition from the source dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineColumnLikeArray (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Defines a column in the target dataset based on an array definition from the source dataset.
epicsShareFuncSDDS int32_t	SDDS_TransferAllColumnDefinitions (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source, uint32_t mode)
	Transfers all column definitions from a source dataset to a target dataset.
epicsShareFuncSDDS int32_t	SDDS_ParseNamelist (void *data, SDDS_FIELD_INFORMATION *fieldInfo, int32_t fieldInfos, char *s)
	Parse a namelist string and populate the corresponding data structure.
epicsShareFuncSDDS PARAMETER_DEFINITION *	SDDS_GetParameterDefinition (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the definition of a specified parameter from the SDDS dataset.
epicsShareFuncSDDS PARAMETER_DEFINITION *	SDDS_CopyParameterDefinition (PARAMETER_DEFINITION **target, PARAMETER_DEFINITION *source)
	Creates a copy of a parameter definition.
epicsShareFuncSDDS int32_t	SDDS_FreeParameterDefinition (PARAMETER_DEFINITION *source)
	Frees memory allocated for a parameter definition.
epicsShareFuncSDDS int32_t	SDDS_TransferParameterDefinition (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Transfers a parameter definition from a source dataset to a target dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineParameterLikeColumn (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Defines a parameter in the target dataset based on a column definition from the source dataset.
epicsShareFuncSDDS int32_t	SDDS_DefineParameterLikeArray (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Defines a parameter in the target dataset based on an array definition from the source dataset.
epicsShareFuncSDDS int32_t	SDDS_TransferAllParameterDefinitions (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source, uint32_t mode)
	Transfers all parameter definitions from a source dataset to a target dataset.
epicsShareFuncSDDS ARRAY_DEFINITION *	SDDS_GetArrayDefinition (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the definition of a specified array from the SDDS dataset.
epicsShareFuncSDDS ARRAY_DEFINITION *	SDDS_CopyArrayDefinition (ARRAY_DEFINITION **target, ARRAY_DEFINITION *source)
	Creates a copy of an array definition.
epicsShareFuncSDDS int32_t	SDDS_FreeArrayDefinition (ARRAY_DEFINITION *source)
	Frees memory allocated for an array definition.
epicsShareFuncSDDS int32_t	SDDS_TransferArrayDefinition (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Transfers an array definition from a source dataset to a target dataset.
epicsShareFuncSDDS int32_t	SDDS_TransferAllArrayDefinitions (SDDS_DATASET *SDDS_target, SDDS_DATASET *SDDS_source, uint32_t mode)
	Transfers all array definitions from a source dataset to a target dataset.
epicsShareFuncSDDS ASSOCIATE_DEFINITION *	SDDS_GetAssociateDefinition (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the definition of a specified associate from the SDDS dataset.
epicsShareFuncSDDS ASSOCIATE_DEFINITION *	SDDS_CopyAssociateDefinition (ASSOCIATE_DEFINITION **target, ASSOCIATE_DEFINITION *source)
	Creates a copy of an associate definition.
epicsShareFuncSDDS int32_t	SDDS_FreeAssociateDefinition (ASSOCIATE_DEFINITION *source)
	Frees memory allocated for an associate definition.
epicsShareFuncSDDS int32_t	SDDS_TransferAssociateDefinition (SDDS_DATASET *target, SDDS_DATASET *source, char *name, char *newName)
	Transfers an associate definition from a source dataset to a target dataset.
epicsShareFuncSDDS int32_t	SDDS_GetColumnIndex (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the index of a named column in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetParameterIndex (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the index of a named parameter in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetArrayIndex (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the index of a named array in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetAssociateIndex (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the index of a named associate in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_GetColumnType (SDDS_DATASET *SDDS_dataset, int32_t index)
	Retrieves the data type of a column in the SDDS dataset by its index.
epicsShareFuncSDDS int32_t	SDDS_GetNamedColumnType (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the data type of a column in the SDDS dataset by its name.
epicsShareFuncSDDS int32_t	SDDS_GetParameterType (SDDS_DATASET *SDDS_dataset, int32_t index)
	Retrieves the data type of a parameter in the SDDS dataset by its index.
epicsShareFuncSDDS int32_t	SDDS_GetNamedParameterType (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the data type of a parameter in the SDDS dataset by its name.
epicsShareFuncSDDS int32_t	SDDS_GetArrayType (SDDS_DATASET *SDDS_dataset, int32_t index)
	Retrieves the data type of an array in the SDDS dataset by its index.
epicsShareFuncSDDS int32_t	SDDS_GetNamedArrayType (SDDS_DATASET *SDDS_dataset, char *name)
	Retrieves the data type of an array in the SDDS dataset by its name.
epicsShareFuncSDDS int32_t	SDDS_GetTypeSize (int32_t type)
	Retrieves the size in bytes of a specified SDDS data type.
epicsShareFuncSDDS char *	SDDS_GetTypeName (int32_t type)
	Retrieves the name of a specified SDDS data type as a string.
epicsShareFuncSDDS int32_t	SDDS_IdentifyType (char *typeName)
	Identifies the SDDS data type based on its string name.
epicsShareFuncSDDS char *	SDDS_FindColumn (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Finds the first column in the SDDS dataset that matches the specified criteria.
epicsShareFuncSDDS char *	SDDS_FindParameter (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Finds the first parameter in the SDDS dataset that matches the specified criteria.
epicsShareFuncSDDS char *	SDDS_FindArray (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Finds the first array in the SDDS dataset that matches the specified criteria.
epicsShareFuncSDDS int32_t	SDDS_CheckColumn (SDDS_DATASET *SDDS_dataset, char *name, char *units, int32_t type, FILE *fp_message)
	Checks if a column exists in the SDDS dataset with the specified name, units, and type.
epicsShareFuncSDDS int32_t	SDDS_CheckParameter (SDDS_DATASET *SDDS_dataset, char *name, char *units, int32_t type, FILE *fp_message)
	Checks if a parameter exists in the SDDS dataset with the specified name, units, and type.
epicsShareFuncSDDS int32_t	SDDS_CheckArray (SDDS_DATASET *SDDS_dataset, char *name, char *units, int32_t type, FILE *fp_message)
	Checks if an array exists in the SDDS dataset with the specified name, units, and type.
epicsShareFuncSDDS int32_t	SDDS_VerifyArrayExists (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Verifies the existence of an array in the SDDS dataset based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_VerifyColumnExists (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Verifies the existence of a column in the SDDS dataset based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_VerifyParameterExists (SDDS_DATASET *SDDS_dataset, int32_t mode,...)
	Verifies the existence of a parameter in the SDDS dataset based on specified criteria.
epicsShareFuncSDDS int32_t	SDDS_PrintCheckText (FILE *fp, char *name, char *units, int32_t type, char *class_name, int32_t error_code)
	Prints detailed error messages related to SDDS entity checks.
epicsShareFuncSDDS int32_t	SDDS_IsActive (SDDS_DATASET *SDDS_dataset)
	Checks whether an SDDS dataset is currently active.
epicsShareFuncSDDS int32_t	SDDS_ForceInactive (SDDS_DATASET *SDDS_dataset)
	Marks an SDDS dataset as inactive.
epicsShareFuncSDDS int32_t	SDDS_LockFile (FILE *fp, const char *filename, const char *callerName)
	Attempts to lock a specified file.
epicsShareFuncSDDS int32_t	SDDS_FileIsLocked (const char *filename)
	Determines if a specified file is locked.
epicsShareFuncSDDS int32_t	SDDS_BreakIntoLockedFile (char *filename)
	Attempts to override a locked file by creating a temporary copy.
epicsShareFuncSDDS int32_t	SDDS_CopyString (char **target, const char *source)
	Copies a source string to a target string with memory allocation.
epicsShareFuncSDDS int32_t	SDDS_CopyStringArray (char **target, char **source, int64_t n_strings)
	Copies an array of strings from source to target.
epicsShareFuncSDDS int32_t	SDDS_FreeStringArray (char **string, int64_t strings)
	Frees an array of strings by deallocating each individual string.
epicsShareFuncSDDS int32_t	SDDS_VerifyPrintfFormat (const char *format_string, int32_t type)
	Verifies that a printf format string is compatible with a specified data type.
epicsShareFuncSDDS int32_t	SDDS_HasWhitespace (char *string)
	Checks if a string contains any whitespace characters.
epicsShareFuncSDDS char *	fgetsSkipComments (SDDS_DATASET *SDDS_dataset, char *s, int32_t slen, FILE *fp, char skip_char)
	Reads a line from a file while skipping comment lines.
epicsShareFuncSDDS char *	fgetsSkipCommentsResize (SDDS_DATASET *SDDS_dataset, char **s, int32_t *slen, FILE *fp, char skip_char)
	Reads a line from a file with dynamic buffer resizing while skipping comment lines.
epicsShareFuncSDDS void	SDDS_CutOutComments (SDDS_DATASET *SDDS_dataset, char *s, char cc)
	Removes comments from a string based on a specified comment character.
epicsShareFuncSDDS void	SDDS_EscapeNewlines (char *s)
	Escapes newline characters in a string by replacing them with "\\n".
epicsShareFuncSDDS void	SDDS_EscapeQuotes (char *s, char quote_char)
	Escapes quote characters within a string by inserting backslashes.
epicsShareFuncSDDS void	SDDS_UnescapeQuotes (char *s, char quote_char)
	Removes escape characters from quote characters within a string.
epicsShareFuncSDDS int32_t	SDDS_IsQuoted (char *string, char *position, char quotation_mark)
	Checks if a position in a string is within a quoted section.
epicsShareFuncSDDS int32_t	SDDS_GetToken (char *s, char *buffer, int32_t buflen)
	Extracts the next token from a string, handling quoted substrings and escape characters.
epicsShareFuncSDDS int32_t	SDDS_GetToken2 (char *s, char **st, int32_t *strlength, char *buffer, int32_t buflen)
	Extracts the next token from a string, handling quoted substrings and escape characters, with updated string pointers.
epicsShareFuncSDDS int32_t	SDDS_PadToLength (char *string, int32_t length)
	Pads a string with spaces to reach a specified length.
epicsShareFuncSDDS void	SDDS_EscapeCommentCharacters (char *string, char cc)
	Escapes comment characters within a string by inserting backslashes.
epicsShareFuncSDDS void	SDDS_InterpretEscapes (char *s)
	Interprets and converts escape sequences in a string.
epicsShareFuncSDDS int32_t	SDDS_ZeroMemory (void *mem, int64_t n_bytes)
	Sets a block of memory to zero.
epicsShareFuncSDDS int32_t	SDDS_SetMemory (void *mem, int64_t n_elements, int32_t data_type,...)
	Initializes a memory block with a sequence of values based on a specified data type.
epicsShareFuncSDDS int32_t	SDDS_SprintTypedValue (void *data, int64_t index, int32_t type, const char *format, char *buffer, uint32_t mode)
	Formats a data value of a specified type into a string buffer using an optional printf format string.
epicsShareFuncSDDS int32_t	SDDS_SprintTypedValueFactor (void *data, int64_t index, int32_t type, const char *format, char *buffer, uint32_t mode, double factor)
	Reallocates memory to a new size and zero-initializes the additional space.
epicsShareFuncSDDS int32_t	SDDS_PrintTypedValue (void *data, int64_t index, int32_t type, char *format, FILE *fp, uint32_t mode)
	Prints a data value of a specified type using an optional printf format string.
epicsShareFuncSDDS int32_t	SDDS_WriteTypedValue (void *data, int64_t index, int32_t type, char *format, FILE *fp)
	Writes a typed value to an ASCII file stream.
epicsShareFuncSDDS void *	SDDS_CastValue (void *data, int64_t index, int32_t data_type, int32_t desired_type, void *memory)
	Casts a value from one SDDS data type to another.
epicsShareFuncSDDS void	SDDS_RemovePadding (char *s)
	Removes leading and trailing whitespace from a string.
epicsShareFuncSDDS int32_t	SDDS_StringIsBlank (char *s)
	Checks if a string is blank (contains only whitespace characters).
epicsShareFuncSDDS void *	SDDS_AllocateMatrix (int32_t size, int64_t dim1, int64_t dim2)
	Allocates a two-dimensional matrix with zero-initialized elements.
epicsShareFuncSDDS void	SDDS_FreeMatrix (void **ptr, int64_t dim1)
	Frees memory allocated for a two-dimensional matrix.
epicsShareFuncSDDS void	SDDS_FreeArray (SDDS_ARRAY *array)
	Frees memory allocated for an SDDS array structure.
epicsShareFuncSDDS void *	SDDS_MakePointerArray (void *data, int32_t type, int32_t dimensions, int32_t *dimension)
	Creates a multi-dimensional pointer array from a contiguous data block.
epicsShareFuncSDDS int32_t	SDDS_ApplyFactorToParameter (SDDS_DATASET *SDDS_dataset, char *name, double factor)
	Applies a scaling factor to a specific parameter in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ApplyFactorToColumn (SDDS_DATASET *SDDS_dataset, char *name, double factor)
	Applies a scaling factor to all elements of a specific column in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_DeleteParameterFixedValues (SDDS_DATASET *SDDS_dataset)
	Deletes fixed values from all parameters in the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SetDataMode (SDDS_DATASET *SDDS_dataset, int32_t newmode)
	Sets the data mode (ASCII or Binary) for the SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_CheckDataset (SDDS_DATASET *SDDS_dataset, const char *caller)
	Validates the SDDS dataset pointer.
epicsShareFuncSDDS int32_t	SDDS_CheckTabularData (SDDS_DATASET *SDDS_dataset, const char *caller)
	Validates the consistency of tabular data within an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_CheckDatasetStructureSize (int32_t size)
	Verifies that the size of the SDDS_DATASET structure matches the expected size.
epicsShareFuncSDDS uint32_t	SDDS_SetAutoCheckMode (uint32_t newMode)
	Sets the automatic check mode for SDDS dataset validation.
epicsShareFuncSDDS int32_t	SDDS_FlushBuffer (FILE *fp, SDDS_FILEBUFFER *fBuffer)
epicsShareFuncSDDS int32_t	SDDS_BufferedWrite (void *target, int64_t targetSize, FILE *fp, SDDS_FILEBUFFER *fBuffer)
epicsShareFuncSDDS int32_t	SDDS_ScanData (char *string, int32_t type, int32_t field_length, void *data, int64_t index, int32_t is_parameter)
	Scans a string and saves the parsed value into a data pointer according to the specified data type.
epicsShareFuncSDDS int32_t	SDDS_ScanData2 (char *string, char **pstring, int32_t *strlength, int32_t type, int32_t field_length, void *data, int64_t index, int32_t is_parameter)
	Scans a string and saves the parsed value into a data pointer, optimized for long strings.
epicsShareFuncSDDS long double	SDDS_ConvertToLongDouble (int32_t type, void *data, int64_t index)
	Converts a value to long double based on its type.
epicsShareFuncSDDS double	SDDS_ConvertToDouble (int32_t type, void *data, int64_t index)
	Converts a value to double based on its type.
epicsShareFuncSDDS int64_t	SDDS_ConvertToLong64 (int32_t type, void *data, int64_t index)
	Converts a value to a 64-bit integer based on its type.
epicsShareFuncSDDS int32_t	SDDS_ConvertToLong (int32_t type, void *data, int64_t index)
	Converts a value to a 32-bit integer based on its type.
epicsShareFuncSDDS int32_t	SDDS_WriteBinaryString (char *string, FILE *fp, SDDS_FILEBUFFER *fBuffer)
	Writes a binary string to a file with buffering.
epicsShareFuncSDDS int64_t	SDDS_CreateRpnMemory (const char *name, short is_string)
	Stub function for creating RPN memory when RPN_SUPPORT is not enabled.
epicsShareFuncSDDS int64_t	SDDS_CreateRpnArray (char *name)
	Stub function for creating RPN arrays when RPN_SUPPORT is not enabled.
epicsShareFuncSDDS int32_t	SDDS_IsBigEndianMachine ()
	Determines whether the current machine uses big-endian byte ordering.
void	SDDS_SwapShort (short *data)
	Swaps the endianness of a short integer.
void	SDDS_SwapUShort (unsigned short *data)
	Swaps the endianness of an unsigned short integer.
epicsShareFuncSDDS void	SDDS_SwapLong (int32_t *data)
	Swaps the endianness of a 32-bit integer.
epicsShareFuncSDDS void	SDDS_SwapULong (uint32_t *data)
	Swaps the endianness of a 32-bit unsigned integer.
epicsShareFuncSDDS void	SDDS_SwapLong64 (int64_t *data)
	Swaps the endianness of a 64-bit integer.
epicsShareFuncSDDS void	SDDS_SwapULong64 (uint64_t *data)
	Swaps the endianness of a 64-bit unsigned integer.
void	SDDS_SwapFloat (float *data)
	Swaps the endianness of a float.
void	SDDS_SwapDouble (double *data)
	Swaps the endianness of a double.
void	SDDS_SwapLongDouble (long double *data)
	Swaps the endianness of a long double.
epicsShareFuncSDDS int32_t	SDDS_SwapEndsArrayData (SDDS_DATASET *SDDSin)
	Swaps the endianness of the array data in an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SwapEndsParameterData (SDDS_DATASET *SDDSin)
	Swaps the endianness of the parameter data in an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_SwapEndsColumnData (SDDS_DATASET *SDDSin)
	Swaps the endianness of the column data in an SDDS dataset.
epicsShareFuncSDDS int32_t	SDDS_ReadNonNativePage (SDDS_DATASET *SDDS_dataset)
	Reads a non-native endian page from an SDDS dataset.
int32_t	SDDS_ReadNonNativePageSparse (SDDS_DATASET *SDDS_dataset, uint32_t mode, int64_t sparse_interval, int64_t sparse_offset)
	Reads a sparse non-native endian page from an SDDS dataset.
int32_t	SDDS_ReadNonNativeBinaryPage (SDDS_DATASET *SDDS_dataset, int64_t sparse_interval, int64_t sparse_offset)
	Reads a non-native endian binary page from an SDDS dataset.
int32_t	SDDS_ReadNonNativeBinaryParameters (SDDS_DATASET *SDDS_dataset)
	Reads non-native endian binary parameters from an SDDS dataset.
int32_t	SDDS_ReadNonNativeBinaryArrays (SDDS_DATASET *SDDS_dataset)
	Reads non-native endian binary arrays from an SDDS dataset.
int32_t	SDDS_ReadNonNativeBinaryRow (SDDS_DATASET *SDDS_dataset, int64_t row, int32_t skip)
	Reads a non-native endian binary row from an SDDS dataset.
char *	SDDS_ReadNonNativeBinaryString (FILE *fp, SDDS_FILEBUFFER *fBuffer, int32_t skip)
	Reads a non-native endian binary string from a file.
epicsShareFuncSDDS int32_t	SDDS_WriteNonNativeBinaryPage (SDDS_DATASET *SDDS_dataset)
	Writes a non-native endian binary page to an SDDS dataset.
int32_t	SDDS_WriteNonNativeBinaryParameters (SDDS_DATASET *SDDS_dataset)
	Writes non-native endian binary parameters to an SDDS dataset.
int32_t	SDDS_WriteNonNativeBinaryArrays (SDDS_DATASET *SDDS_dataset)
	Writes non-native endian binary arrays to an SDDS dataset.
int32_t	SDDS_WriteNonNativeBinaryRow (SDDS_DATASET *SDDS_dataset, int64_t row)
	Writes a non-native endian binary row to an SDDS dataset.
int32_t	SDDS_WriteNonNativeBinaryString (char *string, FILE *fp, SDDS_FILEBUFFER *fBuffer)
	Writes a non-native endian binary string to a file.
epicsShareFuncSDDS char **	getMatchingSDDSNames (SDDS_DATASET *dataset, char **matchName, int32_t matches, int32_t *names, short match_type)
	Retrieves an array of matching SDDS entity names based on specified criteria.
epicsShareFuncSDDS SDDS_DATASET *	SDDS_CreateEmptyDataset (void)
	Creates an empty SDDS dataset.

Typedef Documentation

gzFile

typedef voidp gzFile

Definition at line 215 of file SDDS.h.

SDDS_TABLE

typedef SDDS_DATASET SDDS_TABLE

Definition at line 362 of file SDDS.h.

voidp

typedef void* voidp

Definition at line 214 of file SDDS.h.

Function Documentation

fgetsSkipComments()

epicsShareFuncSDDS char * fgetsSkipComments ( SDDS_DATASET * SDDS_dataset, char * s, int32_t slen, FILE * fp, char skip_char )

extern

Reads a line from a file while skipping comment lines.

This function reads lines from the specified file stream, ignoring lines that begin with the specified skip_char. It also processes special comment lines that start with !# by parsing them using SDDS_ParseSpecialComments.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure, used for processing comments.
[out]	s	Pointer to a character array where the read line will be stored.
[in]	slen	The maximum number of characters to read into s.
[in]	fp	Pointer to the FILE stream to read from.
[in]	skip_char	Character indicating the start of a comment line. Lines beginning with this character will be skipped.

Returns

On success, returns the pointer s containing the read line. If the end of the file is reached or an error occurs, returns NULL.

Note

The function modifies the buffer s by removing comments as determined by SDDS_CutOutComments.

See also

SDDS_CutOutComments

SDDS_ParseSpecialComments

Definition at line 1517 of file SDDS_utils.c.

                                                                                                       {
  while (fgets(s, slen, fp)) {
    if (s[0] != skip_char) {
      SDDS_CutOutComments(SDDS_dataset, s, skip_char);
      return (s);
    } else if (s[1] == '#') {
      SDDS_ParseSpecialComments(SDDS_dataset, s + 2);
    }
  }
  return (NULL);
}

fgetsSkipCommentsResize()

epicsShareFuncSDDS char * fgetsSkipCommentsResize ( SDDS_DATASET * SDDS_dataset, char ** s, int32_t * slen, FILE * fp, char skip_char )

extern

Reads a line from a file with dynamic buffer resizing while skipping comment lines.

This function reads lines from the specified file stream, ignoring lines that begin with the specified skip_char. If a line exceeds the current buffer size, the buffer is dynamically resized to accommodate the entire line. It also processes special comment lines that start with !# by parsing them using SDDS_ParseSpecialComments.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure, used for processing comments.
[in,out]	s	Pointer to a pointer to a character array where the read line will be stored. This buffer may be resized if necessary.
[in,out]	slen	Pointer to an int32_t variable specifying the current size of the buffer s. This value may be updated if the buffer is resized.
[in]	fp	Pointer to the FILE stream to read from.
[in]	skip_char	Character indicating the start of a comment line. Lines beginning with this character will be skipped.

Returns

On success, returns the pointer *s containing the read line. If the end of the file is reached or an error occurs, returns NULL.

Note

The caller is responsible for managing the memory of the buffer *s, including freeing it when no longer needed.

See also

SDDS_CutOutComments

SDDS_ParseSpecialComments

SDDS_Realloc

Definition at line 1548 of file SDDS_utils.c.

                                                                                                               {
  int32_t spaceLeft, length, newLine;
  char *sInsert, *fgetsReturn;
 
  sInsert = *s;
  spaceLeft = *slen;
  newLine = 1;
  while ((fgetsReturn = fgets(sInsert, spaceLeft, fp))) {
    if (newLine && sInsert[0] == '!')
      continue;
    SDDS_CutOutComments(SDDS_dataset, sInsert, skip_char);
    length = strlen(sInsert);
    if (sInsert[length - 1] != '\n' && !feof(fp)) {
      /* buffer wasn't long enough to get the whole line.  Resize and add more data. */
      spaceLeft = *slen;
      *slen = *slen * 2;
      *s = SDDS_Realloc(*s, sizeof(**s) * *slen);
      sInsert = *s + strlen(*s);
      newLine = 0;
    } else
      break;
  }
  if (!fgetsReturn)
    return NULL;
  return (*s);
}

getMatchingSDDSNames()

epicsShareFuncSDDS char ** getMatchingSDDSNames ( SDDS_DATASET * dataset, char ** matchName, int32_t matches, int32_t * names, short type )

extern

Retrieves an array of matching SDDS entity names based on specified criteria.

This function processes a list of SDDS entity names (columns, parameters, or arrays) and selects those that match the provided criteria. It supports wildcard matching and exact matching based on the presence of wildcards in the names.

Parameters

[in]	dataset	Pointer to the SDDS_DATASET structure representing the dataset to be searched.
[in]	matchName	Array of strings containing the names or patterns to match against the dataset's entities.
[in]	matches	The number of names/patterns provided in matchName.
[out]	names	Pointer to an int32_t that will be set to the number of matched names.
[in]	type	Specifies the type of SDDS entity to match. Valid values are: SDDS_MATCH_COLUMN SDDS_MATCH_PARAMETER SDDS_MATCH_ARRAY

Returns

• Returns an array of strings (char **) containing the names of the matched SDDS entities.
• If no matches are found, returns NULL.

Note

• The caller is responsible for freeing the memory allocated for the returned array and the individual strings within it.
• The function uses wild_match for pattern matching when wildcards are present in the matchName entries.

Warning

• Ensure that the type parameter is correctly specified to match the intended SDDS entity class.
• Passing an invalid type value will cause the function to terminate the program with an error message.

See also

SDDS_MatchColumns, SDDS_MatchParameters, SDDS_MatchArrays, SDDS_Realloc, SDDS_CopyString

Definition at line 5647 of file SDDS_utils.c.

                                                                                                                  {
  char **name, **selectedName, *ptr = NULL;
  int32_t names0 = 0, selected = 0, i, j;
  int32_t names32 = 0;
 
  name = selectedName = NULL;
  switch (type) {
  case SDDS_MATCH_COLUMN:
    if (!(name = SDDS_GetColumnNames(dataset, &names0)))
      SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
    break;
  case SDDS_MATCH_PARAMETER:
    if (!(name = SDDS_GetParameterNames(dataset, &names32)))
      SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
    names0 = names32;
    break;
  case SDDS_MATCH_ARRAY:
    if (!(name = SDDS_GetArrayNames(dataset, &names32)))
      SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
    names0 = names32;
    break;
  default:
    SDDS_Bomb("Invalid match type provided.");
    break;
  }
  for (i = 0; i < matches; i++) {
    if (has_wildcards(matchName[i])) {
      ptr = expand_ranges(matchName[i]);
      for (j = 0; j < names0; j++) {
        if (wild_match(name[j], ptr)) {
          selectedName = SDDS_Realloc(selectedName, sizeof(*selectedName) * (selected + 1));
          SDDS_CopyString(&selectedName[selected], name[j]);
          selected++;
        }
      }
      free(ptr);
    } else {
      if (match_string(matchName[i], name, names0, EXACT_MATCH) < 0) {
        fprintf(stderr, "%s not found in input file.\n", matchName[i]);
        exit(1);
      } else {
        selectedName = SDDS_Realloc(selectedName, sizeof(*selectedName) * (selected + 1));
        SDDS_CopyString(&selectedName[selected], matchName[i]);
        selected++;
      }
    }
  }
  SDDS_FreeStringArray(name, names0);
  free(name);
  *names = selected;
  return selectedName;
}

SDDS_AllocateMatrix()

epicsShareFuncSDDS void * SDDS_AllocateMatrix ( int32_t size, int64_t dim1, int64_t dim2 )

extern

Allocates a two-dimensional matrix with zero-initialized elements.

This function allocates memory for a two-dimensional matrix based on the specified dimensions and element size. Each row of the matrix is individually allocated and initialized to zero.

Parameters

[in]	size	The size in bytes of each element in the matrix.
[in]	dim1	The number of rows in the matrix.
[in]	dim2	The number of columns in the matrix.

Returns

• Returns a pointer to the allocated two-dimensional matrix on success.
• Returns NULL if memory allocation fails.

Note

• The function uses calloc to ensure that all elements are zero-initialized.
• The caller is responsible for freeing the allocated memory using SDDS_FreeMatrix.

See also

SDDS_FreeMatrix

calloc

Definition at line 2805 of file SDDS_utils.c.

                                                                    {
  int64_t i;
  void **data;
 
  if (!(data = (void **)SDDS_Malloc(sizeof(*data) * dim1)))
    return (NULL);
  for (i = 0; i < dim1; i++)
    if (!(data[i] = (void *)calloc(dim2, size)))
      return (NULL);
  return (data);
}

SDDS_AppendLayout()

epicsShareFuncSDDS int32_t SDDS_AppendLayout ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source, uint32_t mode )

extern

Appends layout definitions (columns, parameters, associates, arrays) from one SDDS_DATASET to another. Only definitions that do not already exist in the target dataset are added.

Parameters

SDDS_target	Address of the SDDS_DATASET structure to which layout definitions will be appended.
SDDS_source	Address of the SDDS_DATASET structure from which layout definitions will be taken.
mode	Mode flag (currently unused; can be set to 0).

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 158 of file SDDS_copy.c.

                                                                                               {
  SDDS_LAYOUT *source;
  int64_t i;
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_AppendLayout"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_AppendLayout"))
    return (0);
  source = &SDDS_source->layout;
  SDDS_DeferSavingLayout(SDDS_target, 1);
 
  for (i = 0; i < source->n_columns; i++)
    if (SDDS_GetColumnIndex(SDDS_target, source->column_definition[i].name) < 0 &&
        SDDS_DefineColumn(SDDS_target, source->column_definition[i].name,
                          source->column_definition[i].symbol, source->column_definition[i].units, source->column_definition[i].description, source->column_definition[i].format_string, source->column_definition[i].type, source->column_definition[i].field_length) < 0) {
      SDDS_DeferSavingLayout(SDDS_target, 0);
      SDDS_SetError("Unable to define column (SDDS_AppendLayout)");
      return (0);
    }
 
  for (i = 0; i < source->n_parameters; i++)
    if (SDDS_GetParameterIndex(SDDS_target, source->parameter_definition[i].name) < 0 &&
        SDDS_DefineParameter(SDDS_target, source->parameter_definition[i].name,
                             source->parameter_definition[i].symbol, source->parameter_definition[i].units, source->parameter_definition[i].description, source->parameter_definition[i].format_string, source->parameter_definition[i].type, source->parameter_definition[i].fixed_value) < 0) {
      SDDS_DeferSavingLayout(SDDS_target, 0);
      SDDS_SetError("Unable to define parameter (SDDS_AppendLayout)");
      return (0);
    }
 
  for (i = 0; i < source->n_associates; i++)
    if (SDDS_GetAssociateIndex(SDDS_target, source->associate_definition[i].name) < 0 &&
        SDDS_DefineAssociate(SDDS_target, source->associate_definition[i].name, source->associate_definition[i].filename, source->associate_definition[i].path, source->associate_definition[i].description, source->associate_definition[i].contents, source->associate_definition[i].sdds) < 0) {
      SDDS_DeferSavingLayout(SDDS_target, 0);
      SDDS_SetError("Unable to define associate (SDDS_AppendLayout)");
      return (0);
    }
 
  for (i = 0; i < source->n_arrays; i++)
    if (SDDS_GetArrayIndex(SDDS_target, source->array_definition[i].name) < 0 &&
        SDDS_DefineArray(SDDS_target, source->array_definition[i].name,
                         source->array_definition[i].symbol,
                         source->array_definition[i].units, source->array_definition[i].description,
                         source->array_definition[i].format_string, source->array_definition[i].type, source->array_definition[i].field_length, source->array_definition[i].dimensions, source->array_definition[i].group_name) < 0) {
      SDDS_DeferSavingLayout(SDDS_target, 0);
      SDDS_SetError("Unable to define array (SDDS_AppendLayout)");
      return (0);
    }
  SDDS_DeferSavingLayout(SDDS_target, 0);
  if (!SDDS_SaveLayout(SDDS_target)) {
    SDDS_SetError("Unable to save layout (SDDS_AppendLayout)");
    return (0);
  }
  return (1);
}

SDDS_AppendToArrayVararg()

epicsShareFuncSDDS int32_t SDDS_AppendToArrayVararg ( SDDS_DATASET * SDDS_dataset, char * array_name, int32_t mode, void * data_pointer, int32_t elements, ... )

extern

Appends data to an existing array variable in the SDDS dataset using variable arguments for dimensions.

This function appends additional data to a specified array within the current SDDS dataset. The elements parameter specifies the number of new elements to append. The mode parameter controls how the data is interpreted and stored. The dimensions of the array are provided as variable arguments, allowing for flexible handling of multi-dimensional arrays.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
array_name	The name of the array to append data to within the dataset.
mode	Bitwise flags that determine how the array is set. Valid flags include: SDDS_POINTER_ARRAY: Indicates that the array is a pointer array. SDDS_CONTIGUOUS_DATA: Indicates that the data is contiguous in memory.
data_pointer	Pointer to the data to be appended to the array. The data must match the type defined for the array.
elements	The number of elements to append to the array.
...	Variable arguments specifying the dimensions of the array. The number of dimensions should match the array definition.

Returns

Returns 1 on successful appending of the array data. On failure, returns 0 and records an appropriate error message.

See also

SDDS_Realloc, SDDS_CopyStringArray, SDDS_SetError, SDDS_GetArrayIndex

Definition at line 1398 of file SDDS_dataprep.c.

                                                                                                                                        {
  va_list argptr;
  int32_t index, retval, size, startIndex = 0;
  SDDS_LAYOUT *layout;
  SDDS_ARRAY *array;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_AppendToArrayVararg"))
    return (0);
  if (!(mode & SDDS_POINTER_ARRAY) && !(mode & SDDS_CONTIGUOUS_DATA)) {
    SDDS_SetError("Unable to set array--invalid mode (SDDS_AppendToArrayVararg)");
    return (0);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to set array--unknown array name given (SDDS_AppendToArrayVararg)");
    return (0);
  }
  if (!data_pointer) {
    SDDS_SetError("Unable to set array--data pointer is NULL (SDDS_AppendToArrayVararg)");
    return (0);
  }
  if (!SDDS_dataset->array) {
    SDDS_SetError("Unable to set array--internal array pointer is NULL (SDDS_AppendToArrayVararg)");
    return (0);
  }
 
  layout = &SDDS_dataset->layout;
  array = SDDS_dataset->array + index;
  if (!layout->array_definition) {
    SDDS_SetError("Unable to set array--internal array definition pointer is NULL (SDDS_AppendToArrayVararg)");
    return (0);
  }
  array->definition = layout->array_definition + index;
  if (!array->dimension && !(array->dimension = (int32_t *)SDDS_Malloc(sizeof(*array->dimension) * array->definition->dimensions))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArrayVararg)");
    return (0);
  }
  if (!(array->definition->dimensions == 1 || mode & SDDS_CONTIGUOUS_DATA)) {
    SDDS_SetError("Unable to set array--append operation requires contiguous data (SDDS_AppendToArrayVararg)");
    return (0);
  }
 
  va_start(argptr, elements);
 
  /* variable arguments are dimensions */
  retval = 1;
  index = 0;
  array->elements = 1;
  do {
    if ((array->dimension[index] = va_arg(argptr, int32_t)) < 0) {
      SDDS_SetError("Unable to set array--negative dimension given (SDDS_AppendToArrayVararg)");
      retval = 0;
      break;
    }
    array->elements *= array->dimension[index];
  } while (retval == 1 && ++index < array->definition->dimensions);
  va_end(argptr);
 
  if (!retval)
    return (0);
  if (!array->elements)
    return (1);
 
  size = SDDS_type_size[array->definition->type - 1];
  if (!(array->data = SDDS_Realloc(array->data, size * array->elements))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_AppendToArrayVararg)");
    return (0);
  }
 
  startIndex = array->elements - elements;
 
  /* handle 1-d arrays and contiguous data as a special case */
  if (array->definition->dimensions == 1 || mode & SDDS_CONTIGUOUS_DATA) {
    if (array->definition->type != SDDS_STRING)
      memcpy((char *)array->data + size * startIndex, data_pointer, size * elements);
    else if (!SDDS_CopyStringArray(((char **)array->data) + startIndex, data_pointer, elements)) {
      SDDS_SetError("Unable to set array--string copy failure (SDDS_AppendToArrayVararg)");
      return (0);
    }
    return (1);
  }
 
  return (1);
}

SDDS_ApplyFactorToColumn()

epicsShareFuncSDDS int32_t SDDS_ApplyFactorToColumn ( SDDS_DATASET * SDDS_dataset, char * name, double factor )

extern

Applies a scaling factor to all elements of a specific column in the SDDS dataset.

This function multiplies each value in the specified column by the given factor. It first retrieves the column's index and verifies that it is of a numeric type. The scaling operation is performed in-place on each element of the column's data array.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the column to scale.
[in]	factor	The scaling factor to apply to each element of the column.

Returns

• Returns 1 on successful application of the factor to all elements.
• Returns 0 if the column is not found, is non-numeric, or if the dataset lacks the necessary data array.

Note

• The function modifies each element of the column's data array directly within the dataset.
• It supports various numeric SDDS data types.

See also

SDDS_GetColumnIndex

SDDS_NUMERIC_TYPE

SDDS_SetError

Definition at line 3198 of file SDDS_utils.c.

                                                                                        {
  int32_t type, index;
  int64_t i;
  void *data;
 
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0)
    return (0);
  type = SDDS_dataset->layout.column_definition[index].type;
  if (!SDDS_NUMERIC_TYPE(type)) {
    SDDS_SetError("Unable to apply factor to non-numeric column (SDDS_ApplyFactorToColumn)");
    return (0);
  }
  data = SDDS_dataset->data[index];
  for (i = 0; i < SDDS_dataset->n_rows; i++) {
    switch (type) {
    case SDDS_SHORT:
      *((short *)data + i) *= factor;
      break;
    case SDDS_USHORT:
      *((unsigned short *)data + i) *= factor;
      break;
    case SDDS_LONG:
      *((int32_t *)data + i) *= factor;
      break;
    case SDDS_ULONG:
      *((uint32_t *)data + i) *= factor;
      break;
    case SDDS_LONG64:
      *((int64_t *)data + i) *= factor;
      break;
    case SDDS_ULONG64:
      *((uint64_t *)data + i) *= factor;
      break;
    case SDDS_CHARACTER:
      *((char *)data + i) *= factor;
      break;
    case SDDS_FLOAT:
      *((float *)data + i) *= factor;
      break;
    case SDDS_DOUBLE:
      *((double *)data + i) *= factor;
      break;
    case SDDS_LONGDOUBLE:
      *((long double *)data + i) *= factor;
      break;
    default:
      return (0);
    }
  }
  return (1);
}

SDDS_ApplyFactorToParameter()

epicsShareFuncSDDS int32_t SDDS_ApplyFactorToParameter ( SDDS_DATASET * SDDS_dataset, char * name, double factor )

extern

Applies a scaling factor to a specific parameter in the SDDS dataset.

This function multiplies the value of a specified parameter by the given factor. It first retrieves the parameter's index and verifies that it is of a numeric type. The scaling operation is performed in-place on the parameter's data.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the parameter to scale.
[in]	factor	The scaling factor to apply to the parameter's value.

Returns

• Returns 1 on successful application of the factor.
• Returns 0 if the parameter is not found, is non-numeric, or if the dataset lacks the necessary data array.

Note

• The function modifies the parameter's value directly within the dataset.
• It supports various numeric SDDS data types.

See also

SDDS_GetParameterIndex

SDDS_NUMERIC_TYPE

SDDS_SetError

Definition at line 3121 of file SDDS_utils.c.

                                                                                           {
  int32_t type, index;
  void *data;
 
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0)
    return (0);
  type = SDDS_dataset->layout.parameter_definition[index].type;
  if (!SDDS_NUMERIC_TYPE(type)) {
    SDDS_SetError("Unable to apply factor to non-numeric parameter (SDDS_ApplyFactorToParameter)");
    return (0);
  }
  if (!SDDS_dataset->parameter) {
    SDDS_SetError("Unable to apply factor to parameter--no parameter data array (SDDS_ApplyFactorToParameter)");
    return (0);
  }
  if (!(data = SDDS_dataset->parameter[index])) {
    SDDS_SetError("Unable to apply factor to parameter--no data array (SDDS_ApplyFactorToParameter)");
    return (0);
  }
  switch (type) {
  case SDDS_SHORT:
    *((short *)data) *= factor;
    break;
  case SDDS_USHORT:
    *((unsigned short *)data) *= factor;
    break;
  case SDDS_LONG:
    *((int32_t *)data) *= factor;
    break;
  case SDDS_ULONG:
    *((uint32_t *)data) *= factor;
    break;
  case SDDS_LONG64:
    *((int64_t *)data) *= factor;
    break;
  case SDDS_ULONG64:
    *((uint64_t *)data) *= factor;
    break;
  case SDDS_CHARACTER:
    *((char *)data) *= factor;
    break;
  case SDDS_FLOAT:
    *((float *)data) *= factor;
    break;
  case SDDS_DOUBLE:
    *((double *)data) *= factor;
    break;
  case SDDS_LONGDOUBLE:
    *((long double *)data) *= factor;
    break;
  default:
    return (0);
  }
  return (1);
}

SDDS_ArrayCount()

epicsShareFuncSDDS int32_t SDDS_ArrayCount ( SDDS_DATASET * page )

extern

Retrieves the number of arrays in the SDDS dataset.

This function returns the total count of arrays defined in the layout of the provided SDDS dataset.

Parameters

[in]

page

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• The number of arrays (int32_t) in the dataset.
• 0 if the provided dataset pointer is NULL.

Note

• Ensure that the dataset is properly initialized before calling this function.

See also

SDDS_GetArrayIndex, SDDS_CheckArray

Definition at line 5144 of file SDDS_utils.c.

                                            {
  if (!page)
    return 0;
  return page->layout.n_arrays;
}

SDDS_AssertColumnFlags()

epicsShareFuncSDDS int32_t SDDS_AssertColumnFlags ( SDDS_DATASET * SDDS_dataset, uint32_t mode, ... )

extern

Sets acceptance flags for columns based on specified criteria.

This function allows setting column flags in two modes:

• SDDS_FLAG_ARRAY: Sets flags based on an array of flag values.
• SDDS_INDEX_LIMITS: Sets flags for a range of columns to a specific value.

A non-zero flag indicates that a column is "of interest", while a zero flag marks it for rejection.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Operation mode determining how flags are set. Possible values: SDDS_FLAG_ARRAY: c SDDS_AssertColumnFlags(SDDS_DATASET *SDDS_dataset, SDDS_FLAG_ARRAY, int32_t *flagArray, int32_t columnsInArray); SDDS_INDEX_LIMITS: c SDDS_AssertColumnFlags(SDDS_DATASET *SDDS_dataset, SDDS_INDEX_LIMITS, int32_t start, int32_t end, int32_t value);
...	Variable arguments based on the selected mode: SDDS_FLAG_ARRAY: int32_t *flagArray: Array of flag values to assign. int32_t columnsInArray: Number of columns in flagArray. SDDS_INDEX_LIMITS: int32_t start: Starting column index (inclusive). int32_t end: Ending column index (inclusive). int32_t value: Flag value to assign to the specified range.

Returns

• 1 on successful assignment of column flags.
• 0 on failure, with an error message recorded (e.g., invalid parameters, memory issues).

Note

• For SDDS_FLAG_ARRAY, if columnsInArray exceeds the number of allocated columns, it is truncated to fit.
• For SDDS_INDEX_LIMITS, if end exceeds the number of columns, it is adjusted to the last valid column index.

See also

SDDS_SetColumnFlags, SDDS_GetColumnFlags, SDDS_GetColumnFlag

Definition at line 273 of file SDDS_extract.c.

                                                                               {
  int64_t i, j;
  int32_t columns, startColumn, endColumn;
  va_list argptr;
  int32_t retval;
  int32_t *flagArray, flagValue;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_AssertColumnFlags"))
    return (0);
  if ((!SDDS_dataset->column_flag || !SDDS_dataset->column_order) && !SDDS_AllocateColumnFlags(SDDS_dataset))
    return 0;
 
  va_start(argptr, mode);
  retval = 0;
  switch (mode) {
  case SDDS_FLAG_ARRAY:
    if (!(flagArray = va_arg(argptr, int32_t *)))
      SDDS_SetError("NULL flag array pointer seen (SDDS_AssertColumnFlags)");
    else if ((columns = va_arg(argptr, int32_t)) < 0)
      SDDS_SetError("invalid column count seen (SDDS_AssertColumnFlags)");
    else {
      if (columns >= SDDS_dataset->layout.n_columns)
        columns = SDDS_dataset->layout.n_columns - 1;
      for (i = 0; i < columns; i++)
        SDDS_dataset->column_flag[i] = flagArray[i];
      retval = 1;
    }
    break;
  case SDDS_INDEX_LIMITS:
    if ((startColumn = va_arg(argptr, int32_t)) < 0 || (endColumn = va_arg(argptr, int32_t)) < startColumn)
      SDDS_SetError("invalid start and end column values (SDDS_AssertColumnFlags)");
    else {
      flagValue = va_arg(argptr, int32_t);
      if (endColumn >= SDDS_dataset->layout.n_columns || endColumn < 0)
        endColumn = SDDS_dataset->layout.n_columns - 1;
      for (i = startColumn; i <= endColumn; i++)
        SDDS_dataset->column_flag[i] = flagValue;
      retval = 1;
    }
    break;
  default:
    SDDS_SetError("unknown mode passed (SDDS_AssertColumnFlags)");
    break;
  }
  va_end(argptr);
 
  for (i = j = 0; i < SDDS_dataset->layout.n_columns; i++) {
    if (SDDS_dataset->column_flag[i])
      SDDS_dataset->column_order[j++] = i;
  }
 
  SDDS_dataset->n_of_interest = j;
 
  return retval;
}

SDDS_AssertRowFlags()

epicsShareFuncSDDS int32_t SDDS_AssertRowFlags ( SDDS_DATASET * SDDS_dataset, uint32_t mode, ... )

extern

Sets acceptance flags for rows based on specified criteria.

This function allows setting row flags in two modes:

• SDDS_FLAG_ARRAY: Sets flags based on an array of flag values.
• SDDS_INDEX_LIMITS: Sets flags for a range of rows to a specific value.

A non-zero flag indicates that a row is "of interest", while a zero flag marks it for rejection.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Operation mode determining how flags are set. Possible values: SDDS_FLAG_ARRAY: c SDDS_AssertRowFlags(SDDS_DATASET *SDDS_dataset, SDDS_FLAG_ARRAY, int32_t *flagArray, int64_t rowsInArray); SDDS_INDEX_LIMITS: c SDDS_AssertRowFlags(SDDS_DATASET *SDDS_dataset, SDDS_INDEX_LIMITS, int64_t start, int64_t end, int32_t value);
...	Variable arguments based on the selected mode: SDDS_FLAG_ARRAY: int32_t *flagArray: Array of flag values to assign. int64_t rowsInArray: Number of rows in flagArray. SDDS_INDEX_LIMITS: int64_t start: Starting row index (inclusive). int64_t end: Ending row index (inclusive). int32_t value: Flag value to assign to the specified range.

Returns

• 1 on successful assignment of row flags.
• 0 on failure, with an error message recorded (e.g., invalid parameters, memory issues).

Note

• For SDDS_FLAG_ARRAY, if rowsInArray exceeds the number of allocated rows, it is truncated to fit.
• For SDDS_INDEX_LIMITS, if end exceeds the number of rows, it is adjusted to the last valid row index.

See also

SDDS_SetRowFlags, SDDS_GetRowFlags, SDDS_GetRowFlag

Definition at line 148 of file SDDS_extract.c.

{
  int64_t i, rows, startRow, endRow;
  va_list argptr;
  int32_t retval;
  int32_t *flagArray, flagValue;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_AssertRowFlags"))
    return (0);
 
  va_start(argptr, mode);
  retval = 0;
  switch (mode) {
  case SDDS_FLAG_ARRAY:
    if (!(flagArray = va_arg(argptr, int32_t *)))
      SDDS_SetError("NULL flag array pointer seen (SDDS_AssertRowFlags)");
    else if ((rows = va_arg(argptr, int64_t)) < 0)
      SDDS_SetError("invalid row count seen (SDDS_AssertRowFlags)");
    else {
      if (rows >= SDDS_dataset->n_rows)
        rows = SDDS_dataset->n_rows;
      for (i = 0; i < rows; i++)
        SDDS_dataset->row_flag[i] = flagArray[i];
      retval = 1;
    }
    break;
  case SDDS_INDEX_LIMITS:
    if ((startRow = va_arg(argptr, int64_t)) < 0 || (endRow = va_arg(argptr, int64_t)) < startRow)
      SDDS_SetError("invalid start and end row values (SDDS_AssertRowFlags)");
    else {
      flagValue = va_arg(argptr, int32_t);
      if (endRow >= SDDS_dataset->n_rows || endRow < 0)
        endRow = SDDS_dataset->n_rows - 1;
      for (i = startRow; i <= endRow; i++)
        SDDS_dataset->row_flag[i] = flagValue;
      retval = 1;
    }
    break;
  default:
    SDDS_SetError("unknown mode passed (SDDS_AssertRowFlags)");
    break;
  }
 
  va_end(argptr);
  return retval;
}

SDDS_Bomb()

epicsShareFuncSDDS void SDDS_Bomb ( char * message )

extern

Terminates the program after printing an error message and recorded errors.

This function prints a termination message to stderr, invokes SDDS_PrintErrors to display all recorded errors, and then exits the program with a non-zero status.

Parameters

[in]

message

The termination message to be printed. If NULL, a default message "?" is used.

Note

This function does not return; it exits the program.

See also

SDDS_PrintErrors

SDDS_SetError

Definition at line 380 of file SDDS_utils.c.

                              {
  char *programName = SDDS_GetRegisteredProgramNameCopy();
  if (programName)
    fprintf(stderr, "Error (%s): %s\n", programName, message ? message : "?");
  else
    fprintf(stderr, "Error: %s\n", message ? message : "?");
  free(programName);
  SDDS_PrintErrors(stderr, SDDS_VERBOSE_PrintErrors);
  exit(1);
}

SDDS_BreakIntoLockedFile()

epicsShareFuncSDDS int32_t SDDS_BreakIntoLockedFile ( char * filename )

extern

Attempts to override a locked file by creating a temporary copy.

This function tries to break into a locked file by creating a temporary backup and replacing the original file with this backup. The process involves:

• Generating a temporary filename with a .blXXX suffix, where XXX ranges from 1000 to 1019.
• Copying the original file to the temporary file while preserving file attributes.
• Replacing the original file with the temporary copy.

On Windows systems (_WIN32 defined), the function currently does not support breaking into locked files and will output an error message.

Parameters

[in]

filename

The path to the locked file that needs to be overridden.

Returns

• 0 on successful override of the locked file.
• 1 if the operation fails or is not supported on the current platform.

Warning

• The function limits the filename length to 500 characters to prevent buffer overflows.
• Ensure that the necessary permissions are available to create and modify files in the target directory.

Note

• This function relies on the availability of the cp and mv system commands on Unix-like systems.
• The function attempts up to 20 different temporary filenames before failing.

See also

SDDS_FileIsLocked, SDDS_LockFile

Definition at line 3447 of file SDDS_utils.c.

                                                 {
#if defined(_WIN32)
  fprintf(stderr, "Unable to break into locked file\n");
  return (1);
#else
  char buffer[1024];
  int i = 1000, j = 0;
  FILE *fp;
 
  /* limit filename length to 500 so we don't overflow the buffer variable */
  if (strlen(filename) > 500) {
    fprintf(stderr, "Unable to break into locked file\n");
    return (1);
  }
 
  /* find a temporary file name that is not already in use */
  for (i = 1000; i < 1020; i++) {
    sprintf(buffer, "%s.bl%d", filename, i);
    if ((fp = fopen(buffer, "r"))) {
      fclose(fp);
    } else {
      j = i;
      break;
    }
  }
 
  /* if no temporary file names could be found then return with an error message */
  if (j == 0) {
    fprintf(stderr, "Unable to break into locked file\n");
    return (1);
  }
 
  /* copy the original file to the temp file name and preserve the attributes */
  /* the temp file name has to be in the same directory to preserve ACL settings */
  sprintf(buffer, "cp -p %s %s.bl%d", filename, filename, j);
  if (system(buffer) == -1) {
    fprintf(stderr, "Unable to break into locked file\n");
    return (1);
  }
 
  /* move the temp file on top of the original file */
  sprintf(buffer, "mv -f %s.bl%d %s", filename, j, filename);
  if (system(buffer) == -1) {
    fprintf(stderr, "Unable to break into locked file\n");
    return (1);
  }
  return (0);
#endif
}

SDDS_BufferedRead()

epicsShareFuncSDDS int32_t SDDS_BufferedRead ( void * target, int64_t targetSize, FILE * fp, SDDS_FILEBUFFER * fBuffer, int32_t type, int32_t byteOrder )

extern

Reads data from a file into a buffer, optimizing performance with buffering.

This function reads targetSize bytes from the file fp into the memory pointed to by target. It uses the provided fBuffer to buffer file data, improving read performance. If the data type is SDDS_LONGDOUBLE and the long double precision is not 18 digits, it handles conversion to double precision if the environment variable SDDS_LONGDOUBLE_64BITS is not set.

If target is NULL, the function skips over targetSize bytes in the file.

Parameters

target	Pointer to the memory location where the data will be stored. If NULL, the data is skipped.
targetSize	The number of bytes to read from the file.
fp	The file pointer from which data is read.
fBuffer	Pointer to an SDDS_FILEBUFFER structure used for buffering file data.
type	The SDDS data type of the data being read (e.g., SDDS_LONGDOUBLE).
byteOrder	The byte order of the data (SDDS_LITTLEENDIAN or SDDS_BIGENDIAN).

Returns

Returns 1 on success; returns 0 on error.

Definition at line 114 of file SDDS_binary.c.

                                                                                                                                 {
  int float80tofloat64 = 0;
  if ((LDBL_DIG != 18) && (type == SDDS_LONGDOUBLE)) {
    if (getenv("SDDS_LONGDOUBLE_64BITS") == NULL) {
      targetSize *= 2;
      float80tofloat64 = 1;
    }
  }
  if (!fBuffer->bufferSize) {
    /* just read into users buffer or seek if no buffer given */
    if (!target)
      return !fseek(fp, (long)targetSize, SEEK_CUR);
    else {
      if (float80tofloat64) {
        unsigned char x[16];
        double d;
        int64_t shift = 0;
        while (shift < targetSize) {
          if (fread(&x, (size_t)1, 16, fp) != 16)
            return 0;
          d = makeFloat64FromFloat80(x, byteOrder);
          memcpy((char *)target + shift, &d, 8);
          shift += 16;
        }
        return 1;
      } else {
        return fread(target, (size_t)1, (size_t)targetSize, fp) == targetSize;
      }
    }
  }
  if ((fBuffer->bytesLeft -= targetSize) >= 0) {
    /* sufficient data is already in the buffer */
    if (target) {
      if (float80tofloat64) {
        unsigned char x[16];
        double d;
        int64_t shift = 0;
        while (shift < targetSize) {
          memcpy(x, (char *)fBuffer->data + shift, 16);
          d = makeFloat64FromFloat80(x, byteOrder);
          memcpy((char *)target + shift, &d, 8);
          shift += 16;
        }
      } else {
        memcpy((char *)target, (char *)fBuffer->data, targetSize);
      }
    }
    fBuffer->data += targetSize;
    return 1;
  } else {
    /* need to read additional data into buffer */
    int64_t bytesNeeded, offset;
    fBuffer->bytesLeft += targetSize; /* adds back amount subtracted above */
 
    /* first, use the data that is already available. this cleans out the buffer */
    if ((offset = fBuffer->bytesLeft)) {
      /* some data is available in the buffer */
      if (target) {
        if (float80tofloat64) {
          unsigned char x[16];
          double d;
          int64_t shift = 0;
          while (shift < offset) {
            memcpy(x, (char *)fBuffer->data + shift, 16);
            d = makeFloat64FromFloat80(x, byteOrder);
            memcpy((char *)target + shift, &d, 8);
            shift += 16;
          }
        } else {
          memcpy((char *)target, (char *)fBuffer->data, offset);
        }
      }
      bytesNeeded = targetSize - offset;
      fBuffer->bytesLeft = 0;
    } else {
      bytesNeeded = targetSize;
    }
    fBuffer->data = fBuffer->buffer;
 
    if (fBuffer->bufferSize < bytesNeeded) {
      /* just read what is needed directly into user's memory or seek */
      if (!target)
        return !fseek(fp, (long)bytesNeeded, SEEK_CUR);
      else {
        if (float80tofloat64) {
          unsigned char x[16];
          double d;
          int64_t shift = 0;
          while (shift < bytesNeeded) {
            if (fread(&x, (size_t)1, 16, fp) != 16)
              return 0;
            d = makeFloat64FromFloat80(x, byteOrder);
            memcpy((char *)target + offset + shift, &d, 8);
            shift += 16;
          }
          return 1;
        } else {
          return fread((char *)target + offset, (size_t)1, (size_t)bytesNeeded, fp) == bytesNeeded;
        }
      }
    }
 
    /* fill the buffer */
    if ((fBuffer->bytesLeft = fread(fBuffer->data, (size_t)1, (size_t)fBuffer->bufferSize, fp)) < bytesNeeded)
      return 0;
    if (target) {
      if (float80tofloat64) {
        unsigned char x[16];
        double d;
        int64_t shift = 0;
        while (shift < bytesNeeded) {
          memcpy(x, (char *)fBuffer->data + shift, 16);
          d = makeFloat64FromFloat80(x, byteOrder);
          memcpy((char *)target + offset + shift, &d, 8);
          shift += 16;
        }
      } else {
        memcpy((char *)target + offset, (char *)fBuffer->data, bytesNeeded);
      }
    }
    fBuffer->data += bytesNeeded;
    fBuffer->bytesLeft -= bytesNeeded;
    return 1;
  }
}

SDDS_BufferedWrite()

epicsShareFuncSDDS int32_t SDDS_BufferedWrite ( void * target, int64_t targetSize, FILE * fp, SDDS_FILEBUFFER * fBuffer )

extern

Writes data to a file using a buffer to optimize performance.

This function writes targetSize bytes from the memory pointed to by target to the file fp. It uses the provided fBuffer to buffer file data, improving write performance. If the buffer is full, it flushes the buffer to the file before writing more data.

Parameters

target	Pointer to the memory location of the data to write.
targetSize	The number of bytes to write to the file.
fp	The file pointer to which data is written.
fBuffer	Pointer to an SDDS_FILEBUFFER structure used for buffering file data.

Returns

Returns 1 on success; returns 0 on error.

Definition at line 502 of file SDDS_binary.c.

                                                                                                 {
  if (!fBuffer->bufferSize) {
    return fwrite(target, (size_t)1, (size_t)targetSize, fp) == targetSize;
  }
  if ((fBuffer->bytesLeft -= targetSize) >= 0) {
    memcpy((char *)fBuffer->data, (char *)target, targetSize);
    fBuffer->data += targetSize;
#ifdef DEBUG
    fprintf(stderr, "SDDS_BufferedWrite of %" PRId64 " bytes done in-memory, %" PRId64 " bytes left\n", targetSize, fBuffer->bytesLeft);
#endif
    return 1;
  } else {
    int64_t lastLeft;
    /* add back what was subtracted in test above.
     * lastLeft is the number of bytes left in the buffer before doing anything
     * and also the number of bytes from the users data that get copied into the buffer.
     */
    lastLeft = (fBuffer->bytesLeft += targetSize);
    /* copy part of the data into the buffer and write the buffer out */
    memcpy((char *)fBuffer->data, (char *)target, (size_t)fBuffer->bytesLeft);
    if (fwrite(fBuffer->buffer, (size_t)1, (size_t)fBuffer->bufferSize, fp) != fBuffer->bufferSize)
      return 0;
    if (fflush(fp)) {
      SDDS_SetError("Problem flushing file (SDDS_BufferedWrite)");
      SDDS_SetError(strerror(errno));
      return 0;
    }
    /* reset the data pointer and the bytesLeft value.
     * also, determine if the remaining data is too large for the buffer.
     * if so, just write it out.
     */
    fBuffer->data = fBuffer->buffer;
    if ((targetSize -= lastLeft) > (fBuffer->bytesLeft = fBuffer->bufferSize)) {
      return fwrite((char *)target + lastLeft, (size_t)1, (size_t)targetSize, fp) == targetSize;
    }
    /* copy remaining data into the buffer.
     * could do this with a recursive call, but this is more efficient.
     */
    memcpy((char *)fBuffer->data, (char *)target + lastLeft, targetSize);
    fBuffer->data += targetSize;
    fBuffer->bytesLeft -= targetSize;
    return 1;
  }
}

SDDS_Calloc()

epicsShareFuncSDDS void * SDDS_Calloc ( size_t nelem, size_t elem_size )

extern

Allocates zero-initialized memory for an array of elements.

This function is a wrapper around the standard calloc function, used by SDDS routines to allocate memory. It ensures that even if the requested number of elements or element size is zero or negative, a minimum of 1 element with a size of 4 bytes is allocated.

Parameters

[in]	nelem	Number of elements to allocate.
[in]	elem_size	Size in bytes of each element.

Returns

Pointer to the allocated memory. If allocation fails, returns NULL.

Note

If nelem or elem_size is less than or equal to zero, the function allocates memory for one element of 4 bytes by default.

See also

SDDS_Malloc

SDDS_Free

Definition at line 683 of file SDDS_utils.c.

                                                  {
  if (elem_size <= 0)
    elem_size = 4;
  if (nelem <= 0)
    nelem = 1;
  return calloc(nelem, elem_size);
}

SDDS_CastValue()

epicsShareFuncSDDS void * SDDS_CastValue ( void * data, int64_t index, int32_t data_type, int32_t desired_type, void * memory )

extern

Casts a value from one SDDS data type to another.

This function converts a value from its original SDDS data type (data_type) to a desired SDDS data type (desired_type). It retrieves the value at the specified index from the data array and stores the converted value in the provided memory location.

Parameters

[in]	data	Pointer to the data array containing the original values.
[in]	index	The zero-based index of the value to be casted within the data array.
[in]	data_type	The original SDDS data type of the value. Must be one of the SDDS type constants: SDDS_SHORT SDDS_USHORT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_CHARACTER SDDS_FLOAT SDDS_DOUBLE SDDS_LONGDOUBLE
[in]	desired_type	The desired SDDS data type to which the value should be casted. Must be one of the SDDS type constants listed above.
[out]	memory	Pointer to the memory location where the casted value will be stored.

Returns

• Returns a pointer to the memory location containing the casted value on success.
• Returns NULL if the casting fails due to invalid data types or other errors.

Note

• The function does not handle casting for SDDS_STRING types.
• The caller must ensure that the memory location has sufficient space to store the casted value.

See also

SDDS_CopyString

SDDS_SetError

Definition at line 2694 of file SDDS_utils.c.

                                                                                                       {
  long long integer_value;
  long double fp_value;
  if (!data || !memory || data_type == SDDS_STRING || desired_type == SDDS_STRING)
    return (NULL);
  if (data_type == desired_type) {
    memcpy(memory, (char *)data + SDDS_type_size[data_type - 1] * index, SDDS_type_size[data_type - 1]);
    return (memory);
  }
  switch (data_type) {
  case SDDS_SHORT:
    integer_value = *((short *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_USHORT:
    integer_value = *((unsigned short *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_LONG:
    integer_value = *((int32_t *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_ULONG:
    integer_value = *((uint32_t *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_LONG64:
    integer_value = *((int64_t *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_ULONG64:
    integer_value = *((uint64_t *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_CHARACTER:
    integer_value = *((unsigned char *)data + index);
    fp_value = integer_value;
    break;
  case SDDS_FLOAT:
    fp_value = *((float *)data + index);
    integer_value = fp_value;
    break;
  case SDDS_DOUBLE:
    fp_value = *((double *)data + index);
    integer_value = fp_value;
    break;
  case SDDS_LONGDOUBLE:
    fp_value = *((long double *)data + index);
    integer_value = fp_value;
    break;
  default:
    return (NULL);
  }
  switch (desired_type) {
  case SDDS_CHARACTER:
    *((char *)memory) = integer_value;
    break;
  case SDDS_SHORT:
    *((short *)memory) = integer_value;
    break;
  case SDDS_USHORT:
    *((unsigned short *)memory) = integer_value;
    break;
  case SDDS_LONG:
    *((int32_t *)memory) = integer_value;
    break;
  case SDDS_ULONG:
    *((uint32_t *)memory) = integer_value;
    break;
  case SDDS_LONG64:
    *((int64_t *)memory) = integer_value;
    break;
  case SDDS_ULONG64:
    *((uint64_t *)memory) = integer_value;
    break;
  case SDDS_FLOAT:
    *((float *)memory) = fp_value;
    break;
  case SDDS_DOUBLE:
    *((double *)memory) = fp_value;
    break;
  case SDDS_LONGDOUBLE:
    *((long double *)memory) = fp_value;
    break;
  default:
    SDDS_SetError("The impossible has happened (SDDS_CastValue)");
    return (NULL);
  }
  return (memory);
}

SDDS_ChangeArrayInformation()

epicsShareFuncSDDS int32_t SDDS_ChangeArrayInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Modifies a specific field in an array definition within the SDDS dataset.

This function allows you to change a particular field of an array definition, identified either by its name or index. The new value for the field can be provided either as a direct value or as a string, depending on the field type.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field to be modified.
[in]	memory	Pointer to the new value for the field. The type of this pointer should correspond to the data type of the field being modified: For non-string fields, provide a pointer to the appropriate data type (e.g., int32_t*, double*). For string fields, provide a char*.
[in]	mode	A bitwise combination of the following constants to specify how to identify the array and how to pass the new value: SDDS_SET_BY_INDEX: Identify the array by its index. Requires an additional argument of type int32_t (array index). SDDS_SET_BY_NAME: Identify the array by its name. Requires an additional argument of type char* (array name). SDDS_PASS_BY_VALUE: The new value is provided as a direct value (non-string fields). SDDS_PASS_BY_STRING: The new value is provided as a string (string fields).

The valid combinations of mode are:

• SDDS_SET_BY_INDEX | SDDS_PASS_BY_VALUE:

  int32_t SDDS_ChangeArrayInformation(SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode, int32_t array_index);

• SDDS_SET_BY_NAME | SDDS_PASS_BY_VALUE:

  int32_t SDDS_ChangeArrayInformation(SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode, char *array_name);

• SDDS_SET_BY_INDEX | SDDS_PASS_BY_STRING:

  int32_t SDDS_ChangeArrayInformation(SDDS_DATASET *SDDS_dataset, char *field_name, char *memory, int32_t mode, int32_t array_index);

• SDDS_SET_BY_NAME | SDDS_PASS_BY_STRING:

  int32_t SDDS_ChangeArrayInformation(SDDS_DATASET *SDDS_dataset, char *field_name, char *memory, int32_t mode, char *array_name);

Returns

On success, returns the SDDS data type of the modified information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the array name or index based on the mode parameter.

See also

SDDS_GetArrayInformation

Definition at line 597 of file SDDS_info.c.

                                                                                                                   {
  int32_t field_index, type, array_index, givenType;
  ARRAY_DEFINITION *arraydef;
  char *array_name;
  va_list argptr;
  int32_t retval;
  double buffer[4];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ChangeArrayInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_ChangeArrayInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_SET_BY_INDEX) {
    if ((array_index = va_arg(argptr, int32_t)) < 0 || array_index >= SDDS_dataset->layout.n_arrays) {
      SDDS_SetError("Invalid array index passed. (SDDS_ChangeArrayInformation)");
      retval = 0;
    }
  } else {
    if (!(array_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL array name passed. (SDDS_ChangeArrayInformation)");
      retval = 0;
    }
    if ((array_index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
      SDDS_SetError("Unknown array name given (SDDS_ChangeArrayInformation)");
      retval = 0;
    }
  }
  arraydef = SDDS_dataset->layout.array_definition + array_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_ARRAY_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_ArrayFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_ARRAY_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_ChangeArrayInformation)");
    return (0);
  }
  type = SDDS_ArrayFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString(((char **)((char *)arraydef + SDDS_ArrayFieldInformation[field_index].offset)), (char *)memory)) {
      SDDS_SetError("Unable to copy field data (SDDS_ChangeArrayInformation)");
      return (0);
    }
    if (strcmp(field_name, "name") == 0)
      qsort((char *)SDDS_dataset->layout.array_index, SDDS_dataset->layout.n_arrays, sizeof(*SDDS_dataset->layout.array_index), SDDS_CompareIndexedNamesPtr);
  } else {
    if (mode & SDDS_PASS_BY_STRING) {
      if (strcmp(field_name, "type") == 0 && (givenType = SDDS_IdentifyType((char *)memory)) > 0)
        /* the type has been passed as a string (e.g., "double") */
        memcpy((char *)buffer, (char *)&givenType, sizeof(givenType));
      else if (!SDDS_ScanData((char *)memory, type, 0, (void *)buffer, 0, 0)) {
        SDDS_SetError("Unable to scan string data (SDDS_ChangeArrayInformation)");
        return (0);
      }
      memcpy((char *)arraydef + SDDS_ArrayFieldInformation[field_index].offset, (void *)buffer, SDDS_type_size[type - 1]);
    } else
      memcpy((char *)arraydef + SDDS_ArrayFieldInformation[field_index].offset, memory, SDDS_type_size[type - 1]);
  }
 
  return (type);
}

SDDS_ChangeColumnInformation()

epicsShareFuncSDDS int32_t SDDS_ChangeColumnInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Modifies a specific field in a column definition within the SDDS dataset.

This function allows you to change a particular field of a column definition, identified either by its name or index. The new value for the field can be provided either as a direct value or as a string, depending on the field type.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field to be modified.
[in]	memory	Pointer to the new value for the field. The type of this pointer should correspond to the data type of the field being modified: For non-string fields, provide a pointer to the appropriate data type (e.g., int32_t*, double*). For string fields, provide a char*.
[in]	mode	A bitwise combination of the following constants to specify how to identify the column and how to pass the new value: SDDS_SET_BY_INDEX: Identify the column by its index. Requires an additional argument of type int32_t (column index). SDDS_SET_BY_NAME: Identify the column by its name. Requires an additional argument of type char* (column name). SDDS_PASS_BY_VALUE: The new value is provided as a direct value (non-string fields). SDDS_PASS_BY_STRING: The new value is provided as a string (string fields).

The valid combinations of mode are:

• SDDS_SET_BY_INDEX | SDDS_PASS_BY_VALUE:

  int32_t SDDS_ChangeColumnInformation(SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode, int32_t column_index);

• SDDS_SET_BY_NAME | SDDS_PASS_BY_VALUE:

  int32_t SDDS_ChangeColumnInformation(SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode, char *column_name);

• SDDS_SET_BY_INDEX | SDDS_PASS_BY_STRING:

  int32_t SDDS_ChangeColumnInformation(SDDS_DATASET *SDDS_dataset, char *field_name, char *memory, int32_t mode, int32_t column_index);

• SDDS_SET_BY_NAME | SDDS_PASS_BY_STRING:

  int32_t SDDS_ChangeColumnInformation(SDDS_DATASET *SDDS_dataset, char *field_name, char *memory, int32_t mode, char *column_name);

Returns

On success, returns the SDDS data type of the modified information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the column name or index based on the mode parameter.

See also

SDDS_GetColumnInformation

Definition at line 364 of file SDDS_info.c.

                                                                                                                    {
  int32_t field_index, type, givenType;
  int32_t i, column_index;
  COLUMN_DEFINITION *columndef;
  char *column_name;
  va_list argptr;
  int32_t retval;
  double buffer[4];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ChangeColumnInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_ChangeColumnInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_SET_BY_INDEX) {
    if ((column_index = va_arg(argptr, int32_t)) < 0 || column_index >= SDDS_dataset->layout.n_columns) {
      SDDS_SetError("Invalid column index passed. (SDDS_ChangeColumnInformation)");
      retval = 0;
    }
  } else {
    if (!(column_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL column name passed. (SDDS_ChangeColumnInformation)");
      retval = 0;
    }
    if ((column_index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
      SDDS_SetError("Unknown column name given (SDDS_ChangeColumnInformation)");
      retval = 0;
    }
  }
  columndef = SDDS_dataset->layout.column_definition + column_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_COLUMN_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_ColumnFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_COLUMN_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_ChangeColumnInformation)");
    return (0);
  }
  type = SDDS_ColumnFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString(((char **)((char *)columndef + SDDS_ColumnFieldInformation[field_index].offset)), (char *)memory)) {
      SDDS_SetError("Unable to copy field data (SDDS_ChangeColumnInformation)");
      return (0);
    }
    if (strcmp(field_name, "name") == 0) {
      for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
        if (column_index == SDDS_dataset->layout.column_index[i]->index)
          break;
      if (i == SDDS_dataset->layout.n_columns) {
        SDDS_SetError("Unable to copy field data--column indexing problem (SDDS_ChangeColumnInformation)");
        return (0);
      }
      SDDS_dataset->layout.column_index[i]->name = SDDS_dataset->layout.column_definition[column_index].name;
      qsort((char *)SDDS_dataset->layout.column_index, SDDS_dataset->layout.n_columns, sizeof(*SDDS_dataset->layout.column_index), SDDS_CompareIndexedNamesPtr);
    }
  } else {
    if (mode & SDDS_PASS_BY_STRING) {
      if (strcmp(field_name, "type") == 0 && (givenType = SDDS_IdentifyType((char *)memory)) > 0)
        /* the type has been passed as a string (e.g., "double") */
        memcpy((char *)buffer, (char *)&givenType, sizeof(givenType));
      else if (!SDDS_ScanData((char *)memory, type, 0, (void *)buffer, 0, 0)) {
        SDDS_SetError("Unable to scan string data (SDDS_ChangeColumnInformation)");
        return (0);
      }
      memcpy((char *)columndef + SDDS_ColumnFieldInformation[field_index].offset, (void *)buffer, SDDS_type_size[type - 1]);
    } else
      memcpy((char *)columndef + SDDS_ColumnFieldInformation[field_index].offset, memory, SDDS_type_size[type - 1]);
  }
  return (type);
}

SDDS_ChangeParameterInformation()

epicsShareFuncSDDS int32_t SDDS_ChangeParameterInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Modifies a specific field in a parameter definition within the SDDS dataset.

This function allows you to change a particular field of a parameter definition, identified either by its name or index. The new value for the field can be provided either as a direct value or as a string, depending on the field type.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field to be modified.
[in]	memory	Pointer to the new value for the field. The type of this pointer should correspond to the data type of the field being modified: For non-string fields, provide a pointer to the appropriate data type (e.g., int32_t*, double*). For string fields, provide a char*.
[in]	mode	A bitwise combination of the following constants to specify how to identify the parameter and how to pass the new value: SDDS_SET_BY_INDEX: Identify the parameter by its index. Requires an additional argument of type int32_t (parameter index). SDDS_SET_BY_NAME: Identify the parameter by its name. Requires an additional argument of type char* (parameter name). SDDS_PASS_BY_VALUE: The new value is provided as a direct value (non-string fields). SDDS_PASS_BY_STRING: The new value is provided as a string (string fields).

The valid combinations of mode are:

• SDDS_SET_BY_INDEX | SDDS_PASS_BY_VALUE:

  int32_t SDDS_ChangeParameterInformation(SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode, int32_t parameter_index);

• SDDS_SET_BY_NAME | SDDS_PASS_BY_VALUE:

  int32_t SDDS_ChangeParameterInformation(SDDS_DATASET *SDDS_dataset, char *field_name, void *memory, int32_t mode, char *parameter_name);

• SDDS_SET_BY_INDEX | SDDS_PASS_BY_STRING:

  int32_t SDDS_ChangeParameterInformation(SDDS_DATASET *SDDS_dataset, char *field_name, char *memory, int32_t mode, int32_t parameter_index);

• SDDS_SET_BY_NAME | SDDS_PASS_BY_STRING:

  int32_t SDDS_ChangeParameterInformation(SDDS_DATASET *SDDS_dataset, char *field_name, char *memory, int32_t mode, char *parameter_name);

Returns

On success, returns the SDDS data type of the modified information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the parameter name or index based on the mode parameter.

See also

SDDS_GetParameterInformation

Definition at line 485 of file SDDS_info.c.

                                                                                                                       {
  int32_t field_index, type, parameter_index, givenType;
  PARAMETER_DEFINITION *parameterdef;
  char *parameter_name;
  va_list argptr;
  int32_t retval;
  double buffer[4];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ChangeParameterInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_ChangeParameterInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_SET_BY_INDEX) {
    if ((parameter_index = va_arg(argptr, int32_t)) < 0 || parameter_index >= SDDS_dataset->layout.n_parameters) {
      SDDS_SetError("Invalid parameter index passed. (SDDS_ChangeParameterInformation)");
      retval = 0;
    }
  } else {
    if (!(parameter_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL parameter name passed. (SDDS_ChangeParameterInformation)");
      retval = 0;
    }
    if ((parameter_index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
      SDDS_SetError("Unknown parameter name given (SDDS_ChangeParameterInformation)");
      retval = 0;
    }
  }
  parameterdef = SDDS_dataset->layout.parameter_definition + parameter_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_PARAMETER_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_ParameterFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_PARAMETER_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_ChangeParameterInformation)");
    return (0);
  }
  type = SDDS_ParameterFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString(((char **)((char *)parameterdef + SDDS_ParameterFieldInformation[field_index].offset)), (char *)memory)) {
      SDDS_SetError("Unable to copy field data (SDDS_ChangeParameterInformation)");
      return (0);
    }
    if (strcmp(field_name, "name") == 0)
      qsort((char *)SDDS_dataset->layout.parameter_index, SDDS_dataset->layout.n_parameters, sizeof(*SDDS_dataset->layout.parameter_index), SDDS_CompareIndexedNamesPtr);
  } else {
    if (mode & SDDS_PASS_BY_STRING) {
      if (strcmp(field_name, "type") == 0 && (givenType = SDDS_IdentifyType((char *)memory)) > 0)
        /* the type has been passed as a string (e.g., "double") */
        memcpy((char *)buffer, (char *)&givenType, sizeof(givenType));
      else if (!SDDS_ScanData((char *)memory, type, 0, (void *)buffer, 0, 0)) {
        SDDS_SetError("Unable to scan string data (SDDS_ChangeParameterInformation)");
        return (0);
      }
      memcpy((char *)parameterdef + SDDS_ParameterFieldInformation[field_index].offset, (void *)buffer, SDDS_type_size[type - 1]);
    } else
      memcpy((char *)parameterdef + SDDS_ParameterFieldInformation[field_index].offset, memory, SDDS_type_size[type - 1]);
  }
 
  return (type);
}

SDDS_CheckArray()

epicsShareFuncSDDS int32_t SDDS_CheckArray ( SDDS_DATASET * SDDS_dataset, char * name, char * units, int32_t type, FILE * fp_message )

extern

Checks if an array exists in the SDDS dataset with the specified name, units, and type.

This function verifies whether an array with the given name exists within the provided SDDS dataset. Additionally, it can check if the array's units and type match the specified criteria.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to be checked.
[in]	name	The name of the array to check.
[in]	units	The units of the array. This parameter may be NULL if units are not to be validated.
[in]	type	Specifies the expected type of the array. Valid values are: SDDS_ANY_NUMERIC_TYPE SDDS_ANY_FLOATING_TYPE SDDS_ANY_INTEGER_TYPE 0 (if type is to be ignored)
[in]	fp_message	File pointer where error messages will be sent. Typically, this is stderr.

Returns

• SDDS_CHECK_OKAY if the array exists and matches the specified criteria.
• SDDS_CHECK_NONEXISTENT if the array does not exist.
• SDDS_CHECK_WRONGTYPE if the array exists but does not match the specified type.
• SDDS_CHECK_WRONGUNITS if the array exists but does not match the specified units.

Note

• If units is NULL, the function does not perform units validation.
• The function retrieves the array's units and type using SDDS_GetArrayInformation and SDDS_GetArrayType.

Warning

• Ensure that the SDDS dataset is properly initialized and contains arrays before calling this function.
• The function may set error messages using SDDS_SetError if it encounters issues accessing array information.

See also

SDDS_CheckColumn, SDDS_CheckParameter, SDDS_PrintCheckText, SDDS_SetError

Definition at line 4826 of file SDDS_utils.c.

                                                                                                             {
  char *units1;
  int32_t index;
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, name)) < 0)
    return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_NONEXISTENT));
  if (SDDS_VALID_TYPE(type)) {
    if (type != SDDS_GetArrayType(SDDS_dataset, index))
      return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_WRONGTYPE));
  } else {
    switch (type) {
    case 0:
      break;
    case SDDS_ANY_NUMERIC_TYPE:
      if (!SDDS_NUMERIC_TYPE(SDDS_GetArrayType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_WRONGTYPE));
      break;
    case SDDS_ANY_FLOATING_TYPE:
      if (!SDDS_FLOATING_TYPE(SDDS_GetArrayType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_WRONGTYPE));
      break;
    case SDDS_ANY_INTEGER_TYPE:
      if (!SDDS_INTEGER_TYPE(SDDS_GetArrayType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_WRONGTYPE));
      break;
    default:
      return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_WRONGTYPE));
    }
  }
  if (SDDS_GetArrayInformation(SDDS_dataset, "units", &units1, SDDS_GET_BY_NAME, name) != SDDS_STRING) {
    SDDS_SetError("units field of array has wrong data type!");
    SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
  }
  if (!units) {
    /* don't care about units */
    return (SDDS_CHECK_OKAY);
  }
  if (!units1) {
    if (SDDS_StringIsBlank(units))
      return (SDDS_CHECK_OKAY);
    return (SDDS_CHECK_OKAY);
  }
  if (strcmp(units, units1) == 0) {
    free(units1);
    return (SDDS_CHECK_OKAY);
  }
  free(units1);
  return (SDDS_PrintCheckText(fp_message, name, units, type, "array", SDDS_CHECK_WRONGUNITS));
}

SDDS_CheckColumn()

epicsShareFuncSDDS int32_t SDDS_CheckColumn ( SDDS_DATASET * SDDS_dataset, char * name, char * units, int32_t type, FILE * fp_message )

extern

Checks if a column exists in the SDDS dataset with the specified name, units, and type.

This function verifies whether a column with the given name exists in the SDDS dataset and optionally checks if its units and type match the specified criteria.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to be checked.
[in]	name	The name of the column to check.
[in]	units	The units of the column. May be NULL if units are not to be checked.
[in]	type	Specifies the expected type of the column. Valid values are: SDDS_ANY_NUMERIC_TYPE SDDS_ANY_FLOATING_TYPE SDDS_ANY_INTEGER_TYPE 0 (if type is to be ignored)
[in]	fp_message	File pointer where error messages will be sent. Typically, this is stderr.

Returns

• SDDS_CHECK_OKAY if the column exists and matches the specified criteria.
• SDDS_CHECK_NONEXISTENT if the column does not exist.
• SDDS_CHECK_WRONGTYPE if the column exists but does not match the specified type.
• SDDS_CHECK_WRONGUNITS if the column exists but does not match the specified units.

Note

• If units is NULL, the function does not check for units.
• The function retrieves the column's units and type using SDDS_GetColumnInformation and SDDS_GetColumnType.

Warning

• Ensure that the SDDS dataset is properly initialized and contains columns before calling this function.
• The function may set error messages using SDDS_SetError if it encounters issues accessing column information.

See also

SDDS_CheckParameter, SDDS_GetColumnIndex, SDDS_SetError

Definition at line 4646 of file SDDS_utils.c.

                                                                                                              {
  char *units1;
  int32_t index;
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0)
    return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_NONEXISTENT));
  if (SDDS_VALID_TYPE(type)) {
    if (type != SDDS_GetColumnType(SDDS_dataset, index))
      return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGTYPE));
  } else {
    switch (type) {
    case 0:
      break;
    case SDDS_ANY_NUMERIC_TYPE:
      if (!SDDS_NUMERIC_TYPE(SDDS_GetColumnType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGTYPE));
      break;
    case SDDS_ANY_FLOATING_TYPE:
      if (!SDDS_FLOATING_TYPE(SDDS_GetColumnType(SDDS_dataset, index))) {
        return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGTYPE));
      }
      break;
    case SDDS_ANY_INTEGER_TYPE:
      if (!SDDS_INTEGER_TYPE(SDDS_GetColumnType(SDDS_dataset, index))) {
        return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGTYPE));
      }
      break;
    default:
      return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGTYPE));
    }
  }
  if (!units) {
    /* don't care about units */
    return SDDS_CHECK_OKAY;
  }
  if (SDDS_GetColumnInformation(SDDS_dataset, "units", &units1, SDDS_GET_BY_NAME, name) != SDDS_STRING) {
    SDDS_SetError("units field of column has wrong data type!");
    SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
  }
  if (!units1) {
    if (SDDS_StringIsBlank(units))
      return (SDDS_CHECK_OKAY);
    return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGUNITS));
  }
  if (strcmp(units, units1) == 0) {
    free(units1);
    return (SDDS_CHECK_OKAY);
  }
  free(units1);
  return (SDDS_PrintCheckText(fp_message, name, units, type, "column", SDDS_CHECK_WRONGUNITS));
}

SDDS_CheckDataset()

epicsShareFuncSDDS int32_t SDDS_CheckDataset ( SDDS_DATASET * SDDS_dataset, const char * caller )

extern

Validates the SDDS dataset pointer.

This function checks whether the provided SDDS_DATASET pointer is valid (non-NULL). If the check fails, it records an appropriate error message.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be validated.
[in]	caller	Name of the calling function, used for error reporting.

Returns

Returns 1 if the dataset pointer is valid; otherwise, returns 0 and records an error message.

See also

SDDS_SetError

Definition at line 618 of file SDDS_utils.c.

                                                                          {
  char buffer[100];
  if (!SDDS_dataset) {
    sprintf(buffer, "NULL SDDS_DATASET pointer passed to %s", caller);
    SDDS_SetError(buffer);
    return (0);
  }
  return (1);
}

SDDS_CheckDatasetStructureSize()

epicsShareFuncSDDS int32_t SDDS_CheckDatasetStructureSize ( int32_t size )

extern

Verifies that the size of the SDDS_DATASET structure matches the expected size.

This function ensures that the size of the SDDS_DATASET structure used by the program matches the size expected by the SDDS library. This check is crucial to prevent issues related to structure size mismatches, which can occur due to differences in compiler settings or library versions.

Parameters

[in]

size

The size of the SDDS_DATASET structure as determined by the calling program (typically using sizeof(SDDS_DATASET)).

Returns

• 1 if the provided size matches the expected size of the SDDS_DATASET structure.
• 0 if there is a size mismatch, indicating potential incompatibility issues.

Note

• This function should be called during initialization to ensure structural compatibility between the program and the SDDS library.

Warning

• A size mismatch can lead to undefined behavior, including memory corruption and program crashes. Always ensure that both the program and the SDDS library are compiled with compatible settings.

See also

SDDS_DATASET, SDDS_SetError

Definition at line 5070 of file SDDS_utils.c.

                                                     {
  char buffer[100];
  if (size != sizeof(SDDS_DATASET)) {
    SDDS_SetError("passed size is not equal to expected size for SDDS_DATASET structure");
    sprintf(buffer, "Passed size is %" PRId32 ", library size is %" PRId32 "\n", size, (int32_t)sizeof(SDDS_DATASET));
    SDDS_SetError(buffer);
    return 0;
  }
  return 1;
}

SDDS_CheckEndOfFile()

epicsShareFuncSDDS int32_t SDDS_CheckEndOfFile ( SDDS_DATASET * SDDS_dataset )

extern

Checks if the end of the SDDS dataset file has been reached.

Parameters

SDDS_dataset

The SDDS dataset structure.

Returns

Returns 1 if the end of file has been reached, 0 if not, and 2 on error.

Definition at line 1021 of file SDDS_input.c.

                                                        {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_EndOfFile"))
    return (0);
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't check status--file is disconnected (SDDS_EndOfFile)");
    return 2;
  }
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!SDDS_dataset->layout.gzfp) {
      SDDS_SetError("Unable to check status--NULL file pointer (SDDS_EndOfFile)");
      return 2;
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!SDDS_dataset->layout.lzmafp) {
        SDDS_SetError("Unable to check status--NULL file pointer (SDDS_EndOfFile)");
        return 2;
      }
    } else {
      if (!SDDS_dataset->layout.fp) {
        SDDS_SetError("Unable to check status--NULL file pointer (SDDS_EndOfFile)");
        return 2;
      }
    }
#if defined(zLib)
  }
#endif
  if (SDDS_dataset->fBuffer.bufferSize && SDDS_dataset->fBuffer.bytesLeft) {
    return 0;
  }
 
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (gzeof(SDDS_dataset->layout.gzfp))
      return 1;
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (lzma_eof(SDDS_dataset->layout.lzmafp))
        return 1;
    } else {
      if (feof(SDDS_dataset->layout.fp))
        return 1;
    }
#if defined(zLib)
  }
#endif
  return 0;
}

SDDS_CheckParameter()

epicsShareFuncSDDS int32_t SDDS_CheckParameter ( SDDS_DATASET * SDDS_dataset, char * name, char * units, int32_t type, FILE * fp_message )

extern

Checks if a parameter exists in the SDDS dataset with the specified name, units, and type.

This function verifies whether a parameter with the given name exists in the SDDS dataset and optionally checks if its units and type match the specified criteria.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to be checked.
[in]	name	The name of the parameter to check.
[in]	units	The units of the parameter. May be NULL if units are not to be checked.
[in]	type	Specifies the expected type of the parameter. Valid values are: SDDS_ANY_NUMERIC_TYPE SDDS_ANY_FLOATING_TYPE SDDS_ANY_INTEGER_TYPE 0 (if type is to be ignored)
[in]	fp_message	File pointer where error messages will be sent. Typically, this is stderr.

Returns

• SDDS_CHECK_OKAY if the parameter exists and matches the specified criteria.
• SDDS_CHECK_NONEXISTENT if the parameter does not exist.
• SDDS_CHECK_WRONGTYPE if the parameter exists but does not match the specified type.
• SDDS_CHECK_WRONGUNITS if the parameter exists but does not match the specified units.

Note

• If units is NULL, the function does not check for units.
• The function retrieves the parameter's units and type using SDDS_GetParameterInformation and SDDS_GetParameterType.

Warning

• Ensure that the SDDS dataset is properly initialized and contains parameters before calling this function.
• The function may set error messages using SDDS_SetError if it encounters issues accessing parameter information.

See also

SDDS_CheckColumn, SDDS_GetParameterIndex, SDDS_SetError

Definition at line 4737 of file SDDS_utils.c.

                                                                                                                 {
  char *units1;
  int32_t index;
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0)
    return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_NONEXISTENT));
  if (SDDS_VALID_TYPE(type)) {
    if (type != SDDS_GetParameterType(SDDS_dataset, index))
      return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGTYPE));
  } else {
    switch (type) {
    case 0:
      break;
    case SDDS_ANY_NUMERIC_TYPE:
      if (!SDDS_NUMERIC_TYPE(SDDS_GetParameterType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGTYPE));
      break;
    case SDDS_ANY_FLOATING_TYPE:
      if (!SDDS_FLOATING_TYPE(SDDS_GetParameterType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGTYPE));
      break;
    case SDDS_ANY_INTEGER_TYPE:
      if (!SDDS_INTEGER_TYPE(SDDS_GetParameterType(SDDS_dataset, index)))
        return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGTYPE));
      break;
    default:
      return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGTYPE));
    }
  }
  if (!units) {
    /* don't care about units */
    return (SDDS_CHECK_OKAY);
  }
  if (SDDS_GetParameterInformation(SDDS_dataset, "units", &units1, SDDS_GET_BY_NAME, name) != SDDS_STRING) {
    SDDS_SetError("units field of parameter has wrong data type!");
    SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
  }
  if (!units1) {
    if (SDDS_StringIsBlank(units))
      return (SDDS_CHECK_OKAY);
    return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGUNITS));
  }
  if (strcmp(units, units1) == 0) {
    free(units1);
    return (SDDS_CHECK_OKAY);
  }
  free(units1);
  return (SDDS_PrintCheckText(fp_message, name, units, type, "parameter", SDDS_CHECK_WRONGUNITS));
}

SDDS_CheckTabularData()

epicsShareFuncSDDS int32_t SDDS_CheckTabularData ( SDDS_DATASET * SDDS_dataset, const char * caller )

extern

Validates the consistency of tabular data within an SDDS dataset.

This function checks the integrity of tabular data in the given SDDS_DATASET. It verifies that if columns are defined, corresponding row flags and data arrays exist, and that the number of rows matches the column definitions.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be validated.
[in]	caller	Name of the calling function, used for error reporting.

Returns

Returns 1 if the tabular data is consistent and valid; otherwise, returns 0 and records an error message.

Note

This function performs checks only if AutoCheckMode includes TABULAR_DATA_CHECKS.

See also

SDDS_SetAutoCheckMode

SDDS_SetError

Definition at line 643 of file SDDS_utils.c.

                                                                              {
  int64_t i;
  char buffer[100];
  if (!(SDDS_GetLockedAutoCheckMode() & TABULAR_DATA_CHECKS))
    return 1;
  if (SDDS_dataset->layout.n_columns && (!SDDS_dataset->row_flag || !SDDS_dataset->data)) {
    sprintf(buffer, "tabular data is invalid in %s (columns but no row flags or data array)", caller);
    SDDS_SetError(buffer);
    return (0);
  }
  if (SDDS_dataset->layout.n_columns == 0 && SDDS_dataset->n_rows) {
    sprintf(buffer, "tabular data is invalid in %s (no columns present but nonzero row count)", caller);
    SDDS_SetError(buffer);
    return (0);
  }
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++) {
    if (!SDDS_dataset->data[i]) {
      sprintf(buffer, "tabular data is invalid in %s (null data pointer for column %" PRId64 ")", caller, i);
      SDDS_SetError(buffer);
      return (0);
    }
  }
  return (1);
}

SDDS_ClearErrors()

epicsShareFuncSDDS void SDDS_ClearErrors ( void )

extern

Clears all recorded error messages from the SDDS error stack.

This function removes all error messages that have been recorded by SDDS library routines, resetting the error count to zero. It should be called after handling or logging the errors to prepare for future error recording.

Note

After calling this function, SDDS_NumberOfErrors will return zero until new errors are recorded.

See also

SDDS_SetError

SDDS_PrintErrors

Definition at line 354 of file SDDS_utils.c.

                        {
  int32_t i;
  if (error_description) {
    for (i=0; i<n_errors; i++) {
      free(error_description[i]);
      error_description[i] = NULL;
    }
  }
  free(error_description);
  error_description = NULL;
  n_errors = 0;
  n_errors_max = 0;
}

SDDS_ClearPage()

epicsShareFuncSDDS int32_t SDDS_ClearPage ( SDDS_DATASET * SDDS_dataset )

extern

Clears the current page in the SDDS dataset, resetting all data and flags.

This function resets the current data page in the specified SDDS dataset by reinitializing column flags and order. It frees any allocated string data and zeros out the data arrays, parameters, and arrays in the dataset.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure whose current page will be cleared.

Returns

Returns 1 on successful clearing of the page. On failure, returns 0 and records an error message.

See also

SDDS_SetMemory, SDDS_FreeStringData, SDDS_ZeroMemory

Definition at line 194 of file SDDS_dataprep.c.

                                                   {
  SDDS_LAYOUT *layout;
  int64_t i;
  int32_t size;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ClearPage"))
    return 0;
  layout = &SDDS_dataset->layout;
 
  if (layout->n_columns && ((SDDS_dataset->column_flag && !SDDS_SetMemory(SDDS_dataset->column_flag, layout->n_columns, SDDS_LONG, (int32_t)1, (int32_t)0)) || 
                            ((SDDS_dataset->column_order && !SDDS_SetMemory(SDDS_dataset->column_order, layout->n_columns, SDDS_LONG, (int32_t)0, (int32_t)1))))) {
    SDDS_SetError("Unable to start page--memory initialization failure (SDDS_ClearPage)");
    return 0;
  }
  SDDS_FreeStringData(SDDS_dataset);
  if (SDDS_dataset->data) {
    for (i = 0; i < layout->n_columns; i++) {
      size = SDDS_type_size[layout->column_definition[i].type - 1];
      if (SDDS_dataset->data[i])
        SDDS_ZeroMemory(SDDS_dataset->data[i], size * SDDS_dataset->n_rows_allocated);
    }
  }
  if (SDDS_dataset->parameter) {
    for (i = 0; i < layout->n_parameters; i++) {
      size = SDDS_type_size[layout->parameter_definition[i].type - 1];
      SDDS_ZeroMemory(SDDS_dataset->parameter[i], size);
    }
  }
  for (i = 0; i < layout->n_arrays; i++) {
    size = SDDS_type_size[layout->array_definition[i].type - 1];
    if (SDDS_dataset->array && SDDS_dataset->array[i].data && SDDS_dataset->array[i].elements)
      SDDS_ZeroMemory(SDDS_dataset->array[i].data, size * SDDS_dataset->array[i].elements);
  }
  return 1;
}

SDDS_ColumnCount()

epicsShareFuncSDDS int32_t SDDS_ColumnCount ( SDDS_DATASET * page )

extern

Retrieves the number of columns in the SDDS dataset.

This function returns the total count of columns defined in the layout of the provided SDDS dataset.

Parameters

[in]

page

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• The number of columns (int32_t) in the dataset.
• 0 if the provided dataset pointer is NULL.

Note

• Ensure that the dataset is properly initialized before calling this function.

See also

SDDS_GetColumnIndex, SDDS_CheckColumn

Definition at line 5098 of file SDDS_utils.c.

                                             {
  if (!page)
    return 0;
  return page->layout.n_columns;
}

SDDS_ColumnIsOfInterest()

epicsShareFuncSDDS int32_t SDDS_ColumnIsOfInterest ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Determines if a specified column is marked as of interest in the dataset.

This function checks whether the column with the given name is flagged as of interest within the provided SDDS_dataset. It verifies the dataset's validity and then iterates through the columns to find a match based on the column_flag array.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the column to check.

Returns

• Returns 1 if the column is marked as of interest.
• Returns 0 if the column is not marked as of interest or if column_flag is not set.
• Returns -1 if the dataset is invalid.

See also

SDDS_CheckDataset

Definition at line 2494 of file SDDS_utils.c.

                                                                        {
  int64_t i;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ColumnIsOfInterest"))
    return -1;
  if (!SDDS_dataset->column_flag)
    return 0;
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++) {
    if (SDDS_dataset->column_flag[i] && strcmp(name, SDDS_dataset->layout.column_definition[i].name) == 0)
      return 1;
  }
  return 0;
}

SDDS_CompareIndexedNames()

epicsShareFuncSDDS int SDDS_CompareIndexedNames ( const void * s1, const void * s2 )

extern

Compares two SORTED_INDEX structures by their name fields.

This function is used as a comparison callback for sorting functions like qsort. It compares the name fields of two SORTED_INDEX structures lexicographically.

Parameters

[in]	s1	Pointer to the first SORTED_INDEX structure.
[in]	s2	Pointer to the second SORTED_INDEX structure.

Returns

An integer less than, equal to, or greater than zero if the name of s1 is found, respectively, to be less than, to match, or be greater than the name of s2.

See also

qsort

SORTED_INDEX

Definition at line 1338 of file SDDS_utils.c.

                                                             {
  return strcmp(((SORTED_INDEX *)s1)->name, ((SORTED_INDEX *)s2)->name);
}

SDDS_CompareIndexedNamesPtr()

epicsShareFuncSDDS int SDDS_CompareIndexedNamesPtr ( const void * s1, const void * s2 )

extern

Compares two pointers to SORTED_INDEX structures by their name fields.

This function is used as a comparison callback for sorting functions like qsort. It compares the name fields of two SORTED_INDEX structure pointers lexicographically.

Parameters

[in]	s1	Pointer to the first SORTED_INDEX* structure.
[in]	s2	Pointer to the second SORTED_INDEX* structure.

Returns

An integer less than, equal to, or greater than zero if the name of *s1 is found, respectively, to be less than, to match, or be greater than the name of *s2.

See also

qsort

SORTED_INDEX

Definition at line 1358 of file SDDS_utils.c.

                                                                {
  return strcmp((*((SORTED_INDEX **)s1))->name, (*((SORTED_INDEX **)s2))->name);
}

SDDS_ConvertToDouble()

epicsShareFuncSDDS double SDDS_ConvertToDouble ( int32_t type, void * data, int64_t index )

extern

Converts a value to double based on its type.

Parameters

type	The SDDS data type of the value.
data	Pointer to the data array.
index	Index of the element to convert.

Returns

The converted double value, or 0.0 on error.

Definition at line 199 of file SDDS_rpn.c.

                                                                     {
  if (!data) {
    SDDS_SetError("NULL data pointer passed (SDDS_ConvertToDouble)");
    return (0.0);
  }
  switch (type) {
  case SDDS_SHORT:
    return ((double)*((short *)data + index));
  case SDDS_USHORT:
    return ((double)*((unsigned short *)data + index));
  case SDDS_LONG:
    return ((double)*((int32_t *)data + index));
  case SDDS_ULONG:
    return ((double)*((uint32_t *)data + index));
  case SDDS_LONG64:
    return ((double)*((int64_t *)data + index));
  case SDDS_ULONG64:
    return ((double)*((uint64_t *)data + index));
  case SDDS_FLOAT:
    return ((double)*((float *)data + index));
  case SDDS_DOUBLE:
    return (*((double *)data + index));
  case SDDS_LONGDOUBLE:
    return ((double)*((long double *)data + index));
  case SDDS_CHARACTER:
    return ((double)*((unsigned char *)data + index));
  default:
    SDDS_SetError("Invalid data type seen (SDDS_ConvertToDouble)");
    return (0.0);
  }
}

SDDS_ConvertToLong()

epicsShareFuncSDDS int32_t SDDS_ConvertToLong ( int32_t type, void * data, int64_t index )

extern

Converts a value to a 32-bit integer based on its type.

Parameters

type	The SDDS data type of the value.
data	Pointer to the data array.
index	Index of the element to convert.

Returns

The converted 32-bit integer, or 0 on error.

Definition at line 279 of file SDDS_rpn.c.

                                                                    {
  if (!data) {
    SDDS_SetError("NULL data pointer passed (SDDS_ConvertToLong)");
    return (0.0);
  }
  switch (type) {
  case SDDS_LONGDOUBLE:
    return ((int32_t) * ((long double *)data + index));
  case SDDS_DOUBLE:
    return ((int32_t) * ((double *)data + index));
  case SDDS_FLOAT:
    return ((int32_t) * ((float *)data + index));
  case SDDS_SHORT:
    return ((int32_t) * ((short *)data + index));
  case SDDS_USHORT:
    return ((int32_t) * ((unsigned short *)data + index));
  case SDDS_LONG:
    return (*((int32_t *)data + index));
  case SDDS_ULONG:
    return ((int32_t) * ((uint32_t *)data + index));
  case SDDS_LONG64:
    return ((int32_t) * ((int64_t *)data + index));
  case SDDS_ULONG64:
    return ((int32_t) * ((uint64_t *)data + index));
  case SDDS_CHARACTER:
    return ((int32_t) * ((unsigned char *)data + index));
  default:
    SDDS_SetError("Invalid data type seen (SDDS_ConvertToLong)");
    return (0.0);
  }
}

SDDS_ConvertToLong64()

epicsShareFuncSDDS int64_t SDDS_ConvertToLong64 ( int32_t type, void * data, int64_t index )

extern

Converts a value to a 64-bit integer based on its type.

Parameters

type	The SDDS data type of the value.
data	Pointer to the data array.
index	Index of the element to convert.

Returns

The converted 64-bit integer, or 0 on error.

Definition at line 239 of file SDDS_rpn.c.

                                                                      {
  if (!data) {
    SDDS_SetError("NULL data pointer passed (SDDS_ConvertToLong64)");
    return (0.0);
  }
  switch (type) {
  case SDDS_LONGDOUBLE:
    return ((int64_t) * ((long double *)data + index));
  case SDDS_DOUBLE:
    return ((int64_t) * ((double *)data + index));
  case SDDS_FLOAT:
    return ((int64_t) * ((float *)data + index));
  case SDDS_SHORT:
    return ((int64_t) * ((short *)data + index));
  case SDDS_USHORT:
    return ((int64_t) * ((unsigned short *)data + index));
  case SDDS_LONG:
    return ((int64_t) * ((int32_t *)data + index));
  case SDDS_ULONG:
    return ((int64_t) * ((uint32_t *)data + index));
  case SDDS_LONG64:
    return (*((int64_t *)data + index));
  case SDDS_ULONG64:
    return ((int64_t) * ((uint64_t *)data + index));
  case SDDS_CHARACTER:
    return ((int64_t) * ((unsigned char *)data + index));
  default:
    SDDS_SetError("Invalid data type seen (SDDS_ConvertToLong64)");
    return (0.0);
  }
}

SDDS_ConvertToLongDouble()

epicsShareFuncSDDS long double SDDS_ConvertToLongDouble ( int32_t type, void * data, int64_t index )

extern

Converts a value to long double based on its type.

Parameters

type	The SDDS data type of the value.
data	Pointer to the data array.
index	Index of the element to convert.

Returns

The converted long double value, or 0.0 on error.

Definition at line 159 of file SDDS_rpn.c.

                                                                              {
  if (!data) {
    SDDS_SetError("NULL data pointer passed (SDDS_ConvertToLongDouble)");
    return (0.0);
  }
  switch (type) {
  case SDDS_SHORT:
    return ((long double)*((short *)data + index));
  case SDDS_USHORT:
    return ((long double)*((unsigned short *)data + index));
  case SDDS_LONG:
    return ((long double)*((int32_t *)data + index));
  case SDDS_ULONG:
    return ((long double)*((uint32_t *)data + index));
  case SDDS_LONG64:
    return ((long double)*((int64_t *)data + index));
  case SDDS_ULONG64:
    return ((long double)*((uint64_t *)data + index));
  case SDDS_FLOAT:
    return ((long double)*((float *)data + index));
  case SDDS_DOUBLE:
    return ((long double)*((double *)data + index));
  case SDDS_LONGDOUBLE:
    return (*((long double *)data + index));
  case SDDS_CHARACTER:
    return ((long double)*((unsigned char *)data + index));
  default:
    SDDS_SetError("Invalid data type seen (SDDS_ConvertToLongDouble)");
    return (0.0);
  }
}

SDDS_CopyAdditionalRows()

epicsShareFuncSDDS int32_t SDDS_CopyAdditionalRows ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies additional rows from one SDDS_DATASET to another. The rows from SDDS_source are appended to the existing rows in SDDS_target.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure where rows will be appended.
SDDS_source	Pointer to the SDDS_DATASET structure from which rows will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 519 of file SDDS_copy.c.

                                                                                      {
  int64_t i, j, sum;
  int32_t size, target_index;
  char buffer[1024];
 
  if (SDDS_target->n_rows_allocated < (sum = SDDS_target->n_rows + SDDS_source->n_rows) && !SDDS_LengthenTable(SDDS_target, sum - SDDS_target->n_rows_allocated)) {
    SDDS_SetError("Unable to copy additional rows (SDDS_CopyAdditionalRows)");
    return (0);
  }
  if (SDDS_target->layout.n_columns == 0)
    return 1;
  for (i = 0; i < SDDS_source->layout.n_columns; i++) {
    if ((target_index = SDDS_GetColumnIndex(SDDS_target, SDDS_source->layout.column_definition[i].name)) < 0)
      continue;
    size = SDDS_GetTypeSize(SDDS_source->layout.column_definition[i].type);
    if (SDDS_source->layout.column_definition[i].type != SDDS_STRING) {
      if (SDDS_source->layout.column_definition[i].type == SDDS_target->layout.column_definition[target_index].type) {
        memcpy((char *)SDDS_target->data[target_index] + size * SDDS_target->n_rows, SDDS_source->data[i], SDDS_type_size[SDDS_source->layout.column_definition[i].type - 1] * SDDS_source->n_rows);
      } else {
        for (j = 0; j < SDDS_source->n_rows; j++) {
          if (!SDDS_CastValue(SDDS_source->data[i], j,
                              SDDS_source->layout.column_definition[i].type, SDDS_target->layout.column_definition[target_index].type, (char *)(SDDS_target->data[target_index]) + (j + SDDS_target->n_rows) * SDDS_type_size[SDDS_target->layout.column_definition[target_index].type - 1])) {
            sprintf(buffer, "Problem with cast for column %s (SDDS_CopyAdditionalRows)", SDDS_source->layout.column_definition[i].name);
            SDDS_SetError(buffer);
            return 0;
          }
        }
      }
    } else {
      if (SDDS_source->layout.column_definition[i].type != SDDS_target->layout.column_definition[target_index].type) {
        sprintf(buffer, "Unable to copy columns---inconsistent data types for %s (SDDS_CopyAdditionalRows)", SDDS_source->layout.column_definition[i].name);
        SDDS_SetError(buffer);
        return (0);
      }
      if (!SDDS_CopyStringArray((char **)((char *)SDDS_target->data[target_index] + size * SDDS_target->n_rows), SDDS_source->data[i], SDDS_source->n_rows)) {
        SDDS_SetError("Unable to copy columns (SDDS_CopyAdditionalRows)");
        return (0);
      }
    }
    SDDS_target->column_flag[target_index] = 1;
    SDDS_target->column_order[target_index] = target_index;
  }
  SDDS_target->n_rows += SDDS_source->n_rows;
  if (SDDS_target->row_flag)
    for (i = 0; i < SDDS_target->n_rows; i++)
      SDDS_target->row_flag[i] = 1;
 
  return (1);
}

SDDS_CopyArrayDefinition()

epicsShareFuncSDDS ARRAY_DEFINITION * SDDS_CopyArrayDefinition ( ARRAY_DEFINITION ** target, ARRAY_DEFINITION * source )

extern

Creates a copy of an array definition.

This function allocates memory for a new ARRAY_DEFINITION structure and copies the contents from the source array definition to the target. All string fields are duplicated to ensure independent memory management.

Parameters

[out]	target	Pointer to a ARRAY_DEFINITION* where the copied definition will be stored.
[in]	source	Pointer to the ARRAY_DEFINITION structure to be copied. If source is NULL, the target is set to NULL.

Returns

Returns a pointer to the copied ARRAY_DEFINITION structure on success. Returns NULL on failure (e.g., memory allocation failure).

Note

The caller is responsible for freeing the copied array definition using SDDS_FreeArrayDefinition.

See also

SDDS_FreeArrayDefinition

SDDS_Malloc

SDDS_CopyString

Definition at line 1274 of file SDDS_utils.c.

                                                                                                {
  if (!target)
    return NULL;
  if (!source)
    return (*target = NULL);
  if (!(*target = (ARRAY_DEFINITION *)SDDS_Malloc(sizeof(**target))) ||
      !SDDS_CopyString(&(*target)->name, source->name) ||
      !SDDS_CopyString(&(*target)->symbol, source->symbol) ||
      !SDDS_CopyString(&(*target)->units, source->units) || !SDDS_CopyString(&(*target)->description, source->description) || !SDDS_CopyString(&(*target)->format_string, source->format_string) || !SDDS_CopyString(&(*target)->group_name, source->group_name))
    return (NULL);
  (*target)->type = source->type;
  (*target)->field_length = source->field_length;
  (*target)->dimensions = source->dimensions;
  return (*target);
}

SDDS_CopyArrays()

epicsShareFuncSDDS int32_t SDDS_CopyArrays ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies array data from one SDDS_DATASET structure into another for arrays with matching names.

Parameters

SDDS_target	Address of the SDDS_DATASET structure into which array data will be copied.
SDDS_source	Address of the SDDS_DATASET structure from which array data will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 334 of file SDDS_copy.c.

                                                                              {
  int32_t i, j, target_index;
  char messageBuffer[1024];
 
  for (i = 0; i < SDDS_source->layout.n_arrays; i++) {
    if ((target_index = SDDS_GetArrayIndex(SDDS_target, SDDS_source->layout.array_definition[i].name)) < 0)
      continue;
    SDDS_target->array[target_index].definition = SDDS_target->layout.array_definition + target_index;
    SDDS_target->array[target_index].elements = SDDS_source->array[i].elements;
    if (!(SDDS_target->array[target_index].dimension = (int32_t *)SDDS_Malloc(sizeof(*SDDS_target->array[i].dimension) * SDDS_target->array[target_index].definition->dimensions)) ||
        !(SDDS_target->array[target_index].data = SDDS_Realloc(SDDS_target->array[target_index].data, SDDS_type_size[SDDS_target->array[target_index].definition->type - 1] * SDDS_target->array[target_index].elements))) {
      SDDS_SetError("Unable to copy arrays--allocation failure (SDDS_CopyArrays)");
      return (0);
    }
 
    for (j = 0; j < SDDS_target->array[target_index].definition->dimensions; j++)
      SDDS_target->array[target_index].dimension[j] = SDDS_source->array[i].dimension[j];
    if (!SDDS_source->array[i].data) {
      SDDS_target->array[target_index].data = NULL;
      continue;
    }
    if (SDDS_source->layout.array_definition[i].type != SDDS_target->layout.array_definition[target_index].type) {
      if (!SDDS_NUMERIC_TYPE(SDDS_source->layout.array_definition[i].type) || !SDDS_NUMERIC_TYPE(SDDS_target->layout.array_definition[target_index].type)) {
        sprintf(messageBuffer, "Can't cast between nonnumeric types for parameters %s and %s (SDDS_CopyArrays)", SDDS_source->layout.array_definition[i].name, SDDS_target->layout.array_definition[target_index].name);
        SDDS_SetError(messageBuffer);
        return 0;
      }
      for (j = 0; j < SDDS_source->array[i].elements; j++) {
        if (!SDDS_CastValue(SDDS_source->array[i].data, j, SDDS_source->layout.array_definition[i].type, SDDS_target->layout.array_definition[target_index].type, (char *)(SDDS_target->array[target_index].data) + j * SDDS_type_size[SDDS_target->layout.array_definition[target_index].type - 1])) {
          SDDS_SetError("Problem with cast (SDDS_CopyArrays)");
          return 0;
        }
      }
    } else {
      if (SDDS_target->array[target_index].definition->type != SDDS_STRING)
        memcpy(SDDS_target->array[target_index].data, SDDS_source->array[i].data, SDDS_type_size[SDDS_target->array[target_index].definition->type - 1] * SDDS_target->array[target_index].elements);
      else if (!SDDS_CopyStringArray(SDDS_target->array[target_index].data, SDDS_source->array[i].data, SDDS_target->array[target_index].elements)) {
        SDDS_SetError("Unable to copy arrays (SDDS_CopyArrays)");
        return (0);
      }
    }
  }
  return (1);
}

SDDS_CopyAssociateDefinition()

epicsShareFuncSDDS ASSOCIATE_DEFINITION * SDDS_CopyAssociateDefinition ( ASSOCIATE_DEFINITION ** target, ASSOCIATE_DEFINITION * source )

extern

Creates a copy of an associate definition.

This function allocates memory for a new ASSOCIATE_DEFINITION structure and copies the contents from the source associate definition to the target. All string fields are duplicated to ensure independent memory management.

Parameters

[out]	target	Pointer to a ASSOCIATE_DEFINITION* where the copied definition will be stored.
[in]	source	Pointer to the ASSOCIATE_DEFINITION structure to be copied. If source is NULL, the target is set to NULL.

Returns

Returns a pointer to the copied ASSOCIATE_DEFINITION structure on success. Returns NULL on failure (e.g., memory allocation failure).

Note

The caller is responsible for freeing the copied associate definition using SDDS_FreeAssociateDefinition.

See also

SDDS_FreeAssociateDefinition

SDDS_Malloc

SDDS_CopyString

Definition at line 986 of file SDDS_utils.c.

                                                                                                                {
  if (!source)
    return (*target = NULL);
  if (!(*target = (ASSOCIATE_DEFINITION *)SDDS_Malloc(sizeof(**target))) ||
      !SDDS_CopyString(&(*target)->name, source->name) || !SDDS_CopyString(&(*target)->filename, source->filename) || !SDDS_CopyString(&(*target)->path, source->path) || !SDDS_CopyString(&(*target)->description, source->description) || !SDDS_CopyString(&(*target)->contents, source->contents))
    return (NULL);
  (*target)->sdds = source->sdds;
  return (*target);
}

SDDS_CopyColumnDefinition()

epicsShareFuncSDDS COLUMN_DEFINITION * SDDS_CopyColumnDefinition ( COLUMN_DEFINITION ** target, COLUMN_DEFINITION * source )

extern

Creates a copy of a column definition.

This function allocates memory for a new COLUMN_DEFINITION structure and copies the contents from the source column definition to the target. All string fields are duplicated to ensure independent memory management.

Parameters

[out]	target	Pointer to a COLUMN_DEFINITION* where the copied definition will be stored.
[in]	source	Pointer to the COLUMN_DEFINITION structure to be copied. If source is NULL, the target is set to NULL.

Returns

Returns a pointer to the copied COLUMN_DEFINITION structure on success. Returns NULL on failure (e.g., memory allocation failure).

Note

The caller is responsible for freeing the copied column definition using SDDS_FreeColumnDefinition.

See also

SDDS_FreeColumnDefinition

SDDS_Malloc

SDDS_CopyString

Definition at line 1078 of file SDDS_utils.c.

                                                                                                    {
  if (!target)
    return NULL;
  if (!source)
    return (*target = NULL);
  if (!(*target = (COLUMN_DEFINITION *)SDDS_Malloc(sizeof(**target))) ||
      !SDDS_CopyString(&(*target)->name, source->name) ||
      !SDDS_CopyString(&(*target)->symbol, source->symbol) || !SDDS_CopyString(&(*target)->units, source->units) || !SDDS_CopyString(&(*target)->description, source->description) || !SDDS_CopyString(&(*target)->format_string, source->format_string))
    return (NULL);
  (*target)->type = source->type;
  (*target)->field_length = source->field_length;
  (*target)->definition_mode = source->definition_mode;
  (*target)->memory_number = source->memory_number;
  return (*target);
}

SDDS_CopyColumns()

epicsShareFuncSDDS int32_t SDDS_CopyColumns ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies column data from one SDDS_DATASET structure into another for columns with matching names.

Parameters

SDDS_target	Address of the SDDS_DATASET structure into which column data will be copied.
SDDS_source	Address of the SDDS_DATASET structure from which column data will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 387 of file SDDS_copy.c.

                                                                               {
  int64_t i, j;
  int32_t target_index;
  SDDS_target->n_rows = 0;
  if (SDDS_target->layout.n_columns && SDDS_target->n_rows_allocated < SDDS_source->n_rows) {
    SDDS_SetError("Unable to copy columns--insufficient memory allocated to target table");
    return (0);
  }
  if (!SDDS_target->layout.n_columns)
    return 1;
  for (i = 0; i < SDDS_source->layout.n_columns; i++) {
    if ((target_index = SDDS_GetColumnIndex(SDDS_target, SDDS_source->layout.column_definition[i].name)) < 0)
      continue;
    if (SDDS_source->layout.column_definition[i].type != SDDS_STRING) {
      if (SDDS_source->layout.column_definition[i].type == SDDS_target->layout.column_definition[target_index].type)
        memcpy(SDDS_target->data[target_index], SDDS_source->data[i], SDDS_type_size[SDDS_source->layout.column_definition[i].type - 1] * SDDS_source->n_rows);
      else {
        /* Do a cast between the source and target types, if they are both numeric */
        if (!SDDS_NUMERIC_TYPE(SDDS_source->layout.column_definition[i].type) || !SDDS_NUMERIC_TYPE(SDDS_target->layout.column_definition[target_index].type)) {
          SDDS_SetError("Can't cast between nonnumeric types (SDDS_CopyColumns)");
          return 0;
        }
        for (j = 0; j < SDDS_source->n_rows; j++) {
          if (!SDDS_CastValue(SDDS_source->data[i], j, SDDS_source->layout.column_definition[i].type, SDDS_target->layout.column_definition[target_index].type, (char *)(SDDS_target->data[target_index]) + j * SDDS_type_size[SDDS_target->layout.column_definition[target_index].type - 1])) {
            SDDS_SetError("Problem with cast (SDDS_CopyColumns)");
            return 0;
          }
        }
      }
    } else if (!SDDS_CopyStringArray(SDDS_target->data[target_index], SDDS_source->data[i], SDDS_source->n_rows)) {
      SDDS_SetError("Unable to copy columns (SDDS_CopyColumns)");
      return (0);
    }
    SDDS_target->column_flag[target_index] = 1;
    SDDS_target->column_order[target_index] = target_index;
  }
  SDDS_target->n_rows = SDDS_source->n_rows;
  if (SDDS_target->row_flag)
    for (i = 0; i < SDDS_target->n_rows; i++)
      SDDS_target->row_flag[i] = 1;
  return (1);
}

SDDS_CopyLayout()

epicsShareFuncSDDS int32_t SDDS_CopyLayout ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies the entire layout (including version, data mode, description, contents, columns, parameters, associates, and arrays) from one SDDS_DATASET to another. The target dataset's existing layout will be replaced.

Parameters

SDDS_target	Address of the SDDS_DATASET structure into which the layout will be copied.
SDDS_source	Address of the SDDS_DATASET structure from which the layout will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 222 of file SDDS_copy.c.

                                                                              {
  SDDS_LAYOUT *target, *source;
  int64_t i;
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_CopyLayout"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_CopyLayout"))
    return (0);
  target = &SDDS_target->layout;
  source = &SDDS_source->layout;
  target->version = source->version;
  target->data_mode = source->data_mode;
  target->data_mode.no_row_counts = 0;
  target->data_mode.fixed_row_count = 0;
  target->data_mode.column_memory_mode = DEFAULT_COLUMN_MEMORY_MODE;
  target->layout_written = 0;
  target->byteOrderDeclared = 0;
  if (source->description)
    SDDS_CopyString(&target->description, source->description);
  if (source->contents)
    SDDS_CopyString(&target->contents, source->contents);
  SDDS_DeferSavingLayout(SDDS_target, 1);
  for (i = 0; i < source->n_columns; i++)
    if (SDDS_DefineColumn(SDDS_target, source->column_definition[i].name, source->column_definition[i].symbol,
                          source->column_definition[i].units, source->column_definition[i].description, source->column_definition[i].format_string, source->column_definition[i].type, source->column_definition[i].field_length) < 0) {
      SDDS_SetError("Unable to define column (SDDS_CopyLayout)");
      return (0);
    }
  for (i = 0; i < source->n_parameters; i++)
    if (SDDS_DefineParameter(SDDS_target, source->parameter_definition[i].name, source->parameter_definition[i].symbol,
                             source->parameter_definition[i].units, source->parameter_definition[i].description, source->parameter_definition[i].format_string, source->parameter_definition[i].type, source->parameter_definition[i].fixed_value) < 0) {
      SDDS_SetError("Unable to define parameter (SDDS_CopyLayout)");
      return (0);
    }
 
  for (i = 0; i < source->n_associates; i++)
    if (SDDS_DefineAssociate(SDDS_target, source->associate_definition[i].name, source->associate_definition[i].filename, source->associate_definition[i].path, source->associate_definition[i].description, source->associate_definition[i].contents, source->associate_definition[i].sdds) < 0) {
      SDDS_SetError("Unable to define associate (SDDS_CopyLayout)");
      return (0);
    }
 
  for (i = 0; i < source->n_arrays; i++)
    if (SDDS_DefineArray(SDDS_target, source->array_definition[i].name, source->array_definition[i].symbol,
                         source->array_definition[i].units, source->array_definition[i].description,
                         source->array_definition[i].format_string, source->array_definition[i].type, source->array_definition[i].field_length, source->array_definition[i].dimensions, source->array_definition[i].group_name) < 0) {
      SDDS_SetError("Unable to define array (SDDS_CopyLayout)");
      return (0);
    }
  SDDS_DeferSavingLayout(SDDS_target, 0);
  if (!SDDS_SaveLayout(SDDS_target)) {
    SDDS_SetError("Unable to save layout (SDDS_CopyLayout)");
    return (0);
  }
  return (1);
}

SDDS_CopyPage()

epicsShareFuncSDDS int32_t SDDS_CopyPage ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies the data from one SDDS_DATASET structure to another. This includes parameters, arrays, and columns.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure where data will be copied to.
SDDS_source	Pointer to the SDDS_DATASET structure from which data will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 578 of file SDDS_copy.c.

                                                                            {
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_CopyPage"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_CopyPage"))
    return (0);
 
  if (!SDDS_StartPage(SDDS_target, SDDS_target->layout.n_columns ? SDDS_source->n_rows : 0)) {
    SDDS_SetError("Unable to copy page (SDDS_CopyPage)");
    return (0);
  }
  if (!SDDS_CopyParameters(SDDS_target, SDDS_source))
    return (0);
  if (!SDDS_CopyArrays(SDDS_target, SDDS_source))
    return (0);
  if (!SDDS_CopyColumns(SDDS_target, SDDS_source))
    return (0);
  return (1);
}

SDDS_CopyParameterDefinition()

epicsShareFuncSDDS PARAMETER_DEFINITION * SDDS_CopyParameterDefinition ( PARAMETER_DEFINITION ** target, PARAMETER_DEFINITION * source )

extern

Creates a copy of a parameter definition.

This function allocates memory for a new PARAMETER_DEFINITION structure and copies the contents from the source parameter definition to the target. All string fields are duplicated to ensure independent memory management.

Parameters

[out]	target	Pointer to a PARAMETER_DEFINITION* where the copied definition will be stored.
[in]	source	Pointer to the PARAMETER_DEFINITION structure to be copied. If source is NULL, the target is set to NULL.

Returns

Returns a pointer to the copied PARAMETER_DEFINITION structure on success. Returns NULL on failure (e.g., memory allocation failure).

Note

The caller is responsible for freeing the copied parameter definition using SDDS_FreeParameterDefinition.

See also

SDDS_FreeParameterDefinition

SDDS_Malloc

SDDS_CopyString

Definition at line 1175 of file SDDS_utils.c.

                                                                                                                {
  if (!target)
    return NULL;
  if (!source)
    return (*target = NULL);
  if (!(*target = (PARAMETER_DEFINITION *)SDDS_Malloc(sizeof(**target))) ||
      !SDDS_CopyString(&(*target)->name, source->name) ||
      !SDDS_CopyString(&(*target)->symbol, source->symbol) ||
      !SDDS_CopyString(&(*target)->units, source->units) || !SDDS_CopyString(&(*target)->description, source->description) || !SDDS_CopyString(&(*target)->format_string, source->format_string) || !SDDS_CopyString(&(*target)->fixed_value, source->fixed_value))
    return (NULL);
  (*target)->type = source->type;
  (*target)->definition_mode = source->definition_mode;
  (*target)->memory_number = source->memory_number;
  return (*target);
}

SDDS_CopyParameters()

epicsShareFuncSDDS int32_t SDDS_CopyParameters ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies parameter values from one SDDS_DATASET structure into another for parameters with matching names.

Parameters

SDDS_target	Address of the SDDS_DATASET structure into which parameter values will be copied.
SDDS_source	Address of the SDDS_DATASET structure from which parameter values will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 286 of file SDDS_copy.c.

                                                                                  {
  int32_t i, target_index;
  char *buffer = NULL; /* will be sized to hold any SDDS data type with room to spare */
  char messageBuffer[1024];
 
  if (!buffer && !(buffer = SDDS_Malloc(sizeof(char) * 16))) {
    SDDS_SetError("Allocation failure (SDDS_CopyParameters)");
    return 0;
  }
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_CopyParameters"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_CopyParameters"))
    return (0);
 
  for (i = 0; i < SDDS_source->layout.n_parameters; i++) {
    if ((target_index = SDDS_GetParameterIndex(SDDS_target, SDDS_source->layout.parameter_definition[i].name)) < 0)
      continue;
    if (SDDS_source->layout.parameter_definition[i].type != SDDS_target->layout.parameter_definition[target_index].type) {
      if (!SDDS_NUMERIC_TYPE(SDDS_source->layout.parameter_definition[i].type) || !SDDS_NUMERIC_TYPE(SDDS_target->layout.parameter_definition[target_index].type)) {
        sprintf(messageBuffer, "Can't cast between nonnumeric types for parameters %s and %s (SDDS_CopyParameters)", SDDS_source->layout.parameter_definition[i].name, SDDS_target->layout.parameter_definition[target_index].name);
        SDDS_SetError(messageBuffer);
        return 0;
      }
      if (!SDDS_SetParameters(SDDS_target, SDDS_SET_BY_INDEX | SDDS_PASS_BY_REFERENCE, target_index, SDDS_CastValue(SDDS_source->parameter[i], 0, SDDS_source->layout.parameter_definition[i].type, SDDS_target->layout.parameter_definition[target_index].type, buffer), -1)) {
        sprintf(messageBuffer, "Error setting parameter with cast value for parameters %s and %s (SDDS_CopyParameters)", SDDS_source->layout.parameter_definition[i].name, SDDS_target->layout.parameter_definition[target_index].name);
        SDDS_SetError(messageBuffer);
        return 0;
      }
    } else if (!SDDS_SetParameters(SDDS_target, SDDS_SET_BY_INDEX | SDDS_PASS_BY_REFERENCE, target_index, SDDS_source->parameter[i], -1)) {
      sprintf(messageBuffer, "Unable to copy parameters for parameters %s and %s (SDDS_CopyParameters)", SDDS_source->layout.parameter_definition[i].name, SDDS_target->layout.parameter_definition[target_index].name);
      SDDS_SetError(messageBuffer);
      return (0);
    }
  }
  if (buffer)
    free(buffer);
  return (1);
}

SDDS_CopyRow()

epicsShareFuncSDDS int32_t SDDS_CopyRow ( SDDS_DATASET * SDDS_target, int64_t target_row, SDDS_DATASET * SDDS_source, int64_t source_srow )

extern

Copies a row from the source SDDS_DATASET to the target SDDS_DATASET. Only columns that exist in both datasets are copied. The source row is determined by its position among the selected rows.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure where the row will be copied to.
target_row	Index of the row in the target dataset where data will be placed.
SDDS_source	Pointer to the SDDS_DATASET structure from which the row will be copied.
source_srow	Index of the selected row (among rows of interest) in the source dataset.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 778 of file SDDS_copy.c.

                                                                                                                    {
  int64_t i, j, source_row;
  int32_t size, type;
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_CopyRow"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_CopyRow"))
    return (0);
 
  if (target_row >= SDDS_target->n_rows_allocated) {
    SDDS_SetError("Unable to copy row--target page not large enough");
    return (0);
  }
  if (SDDS_target->n_rows <= target_row)
    SDDS_target->n_rows = target_row + 1;
 
  source_row = -1;
  for (i = j = 0; i < SDDS_source->n_rows; i++)
    if (SDDS_source->row_flag[i] && j++ == source_srow) {
      source_row = i;
      break;
    }
 
  if (source_row == -1) {
    SDDS_SetError("Unable to copy row--source selected-row does not exist");
    return (0);
  }
 
  for (i = 0; i < SDDS_target->layout.n_columns; i++) {
    if ((j = SDDS_GetColumnIndex(SDDS_source, SDDS_target->layout.column_definition[i].name)) < 0 || !SDDS_source->column_flag[j])
      continue;
    if ((type = SDDS_GetColumnType(SDDS_target, i)) == SDDS_STRING) {
      if (!SDDS_CopyString(((char ***)SDDS_target->data)[i] + target_row, ((char ***)SDDS_source->data)[j][source_row])) {
        SDDS_SetError("Unable to copy row--string copy failed (SDDS_CopyRow)");
        return (0);
      }
    } else {
      size = SDDS_type_size[type - 1];
      memcpy((char *)SDDS_target->data[i] + size * target_row, (char *)SDDS_source->data[j] + size * source_row, size);
    }
    SDDS_target->row_flag[target_row] = 1;
  }
  return (1);
}

SDDS_CopyRowDirect()

epicsShareFuncSDDS int32_t SDDS_CopyRowDirect ( SDDS_DATASET * SDDS_target, int64_t target_row, SDDS_DATASET * SDDS_source, int64_t source_row )

extern

Copies a specific row from the source SDDS_DATASET to the target SDDS_DATASET. Only columns that exist in both datasets are copied.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure where the row will be copied to.
target_row	Index of the row in the target dataset where data will be placed.
SDDS_source	Pointer to the SDDS_DATASET structure from which the row will be copied.
source_row	Index of the row in the source dataset to be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 834 of file SDDS_copy.c.

                                                                                                                         {
  int64_t i, j;
  int32_t size, type;
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_CopyRow"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_CopyRow"))
    return (0);
 
  if (target_row >= SDDS_target->n_rows_allocated) {
    SDDS_SetError("Unable to copy row--target page not large enough");
    return (0);
  }
  if (SDDS_target->n_rows <= target_row)
    SDDS_target->n_rows = target_row + 1;
  if (source_row >= SDDS_source->n_rows_allocated) {
    SDDS_SetError("Unable to copy row--source row non-existent");
    return (0);
  }
 
  for (i = 0; i < SDDS_target->layout.n_columns; i++) {
    if ((j = SDDS_GetColumnIndex(SDDS_source, SDDS_target->layout.column_definition[i].name)) < 0 || !SDDS_source->column_flag[j])
      continue;
    if ((type = SDDS_GetColumnType(SDDS_target, i)) == SDDS_STRING) {
      if (!SDDS_CopyString(((char ***)SDDS_target->data)[i] + target_row, ((char ***)SDDS_source->data)[j][source_row])) {
        SDDS_SetError("Unable to copy row--string copy failed (SDDS_CopyRow)");
        return (0);
      }
    } else {
      size = SDDS_type_size[type - 1];
      memcpy((char *)SDDS_target->data[i] + size * target_row, (char *)SDDS_source->data[j] + size * source_row, size);
    }
    SDDS_target->row_flag[target_row] = 1;
  }
  return (1);
}

SDDS_CopyRows()

epicsShareFuncSDDS int32_t SDDS_CopyRows ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source, int64_t firstRow, int64_t lastRow )

extern

Copies a range of rows from the source SDDS_DATASET to the target SDDS_DATASET. Only columns that exist in both datasets are copied.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure where rows will be copied to.
SDDS_source	Pointer to the SDDS_DATASET structure from which rows will be copied.
firstRow	Index of the first row to copy from the source dataset.
lastRow	Index of the last row to copy from the source dataset.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 882 of file SDDS_copy.c.

                                                                                                               {
  int64_t i, j, k;
  int32_t size, target_index;
  char buffer[1024];
  int64_t *rowList, roi;
  k = 0;
 
  if (!SDDS_target->layout.n_columns)
    return 1;
  roi = lastRow - firstRow + 1;
  if (roi > SDDS_target->n_rows_allocated) {
    SDDS_SetError("Unable to copy rows of interest--insufficient memory allocated to target page (SDDS_CopyRows)");
    return 0;
  }
  rowList = malloc(sizeof(*rowList) * roi);
  k = 0;
 
  for (j = firstRow; j <= lastRow; j++) {
    rowList[k] = j;
    k++;
  }
 
  for (i = 0; i < SDDS_source->layout.n_columns; i++) {
    if ((target_index = SDDS_GetColumnIndex(SDDS_target, SDDS_source->layout.column_definition[i].name)) < 0)
      continue;
    if (SDDS_source->layout.column_definition[i].type != SDDS_STRING) {
      if (SDDS_source->layout.column_definition[i].type == SDDS_target->layout.column_definition[target_index].type) {
        size = SDDS_type_size[SDDS_source->layout.column_definition[i].type - 1];
        for (k = 0; k < roi; k++) {
 
          memcpy((char *)SDDS_target->data[target_index] + k * size, (char *)SDDS_source->data[i] + rowList[k] * size, SDDS_type_size[SDDS_source->layout.column_definition[i].type - 1]);
        }
      } else {
        for (k = 0; k < roi; k++) {
          if (!SDDS_CastValue(SDDS_source->data[i], rowList[k],
                              SDDS_source->layout.column_definition[i].type, SDDS_target->layout.column_definition[target_index].type, (char *)(SDDS_target->data[target_index]) + k * SDDS_type_size[SDDS_target->layout.column_definition[target_index].type - 1])) {
            sprintf(buffer, "Problem with cast for column %s (SDDS_CopyRows)", SDDS_source->layout.column_definition[i].name);
            SDDS_SetError(buffer);
            return 0;
          }
        }
      }
    } else {
      if (SDDS_source->layout.column_definition[i].type != SDDS_target->layout.column_definition[target_index].type) {
        sprintf(buffer, "Unable to copy columns---inconsistent data types for %s (SDDS_CopyRows)", SDDS_source->layout.column_definition[i].name);
        SDDS_SetError(buffer);
        return (0);
      }
      for (k = 0; k < roi; k++) {
        if (((char **)SDDS_target->data[target_index])[k])
          free(((char **)SDDS_target->data[target_index])[k]);
        if (!SDDS_CopyString(&((char **)SDDS_target->data[target_index])[k], ((char **)SDDS_source->data[i])[rowList[k]])) {
          SDDS_SetError("Unable to copy rows (SDDS_CopyRows)");
          return (0);
        }
      }
    }
    SDDS_target->column_flag[target_index] = 1;
    SDDS_target->column_order[target_index] = target_index;
  }
 
  free(rowList);
 
  SDDS_target->n_rows = roi;
  if (SDDS_target->row_flag) {
    for (i = 0; i < roi; i++) {
      SDDS_target->row_flag[i] = 1;
    }
  }
 
  return (1);
}

SDDS_CopyRowsOfInterest()

epicsShareFuncSDDS int32_t SDDS_CopyRowsOfInterest ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source )

extern

Copies rows of interest from the source SDDS_DATASET to the target SDDS_DATASET for columns with matching names. Rows of interest are those that have their row flags set in the source dataset.

Parameters

SDDS_target	Address of the SDDS_DATASET structure into which rows will be copied.
SDDS_source	Address of the SDDS_DATASET structure from which rows will be copied.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 439 of file SDDS_copy.c.

                                                                                      {
  int64_t i, j, k;
  int32_t size, target_index;
  /*  int32_t rows; */
  char buffer[1024];
  int64_t *rowList, roi;
  k = 0;
 
  if (!SDDS_target->layout.n_columns)
    return 1;
  roi = SDDS_CountRowsOfInterest(SDDS_source);
  if (roi > SDDS_target->n_rows_allocated) {
    SDDS_SetError("Unable to copy rows of interest--insufficient memory allocated to target page (SDDS_CopyRowsOfInterest)");
    return 0;
  }
 
  rowList = malloc(sizeof(*rowList) * roi);
  k = 0;
  for (j = 0; j < SDDS_source->n_rows; j++) {
    if (SDDS_source->row_flag[j]) {
      rowList[k] = j;
      k++;
    }
  }
 
  for (i = 0; i < SDDS_source->layout.n_columns; i++) {
    if ((target_index = SDDS_GetColumnIndex(SDDS_target, SDDS_source->layout.column_definition[i].name)) < 0)
      continue;
    if (SDDS_source->layout.column_definition[i].type != SDDS_STRING) {
      if (SDDS_source->layout.column_definition[i].type == SDDS_target->layout.column_definition[target_index].type) {
        size = SDDS_type_size[SDDS_source->layout.column_definition[i].type - 1];
        for (k = 0; k < roi; k++) {
          memcpy((char *)SDDS_target->data[target_index] + k * size, (char *)SDDS_source->data[i] + rowList[k] * size, SDDS_type_size[SDDS_source->layout.column_definition[i].type - 1]);
        }
      } else {
        for (k = 0; k < roi; k++) {
          if (!SDDS_CastValue(SDDS_source->data[i], rowList[k],
                              SDDS_source->layout.column_definition[i].type, SDDS_target->layout.column_definition[target_index].type, (char *)(SDDS_target->data[target_index]) + k * SDDS_type_size[SDDS_target->layout.column_definition[target_index].type - 1])) {
            sprintf(buffer, "Problem with cast for column %s (SDDS_CopyRowsOfInterest)", SDDS_source->layout.column_definition[i].name);
            SDDS_SetError(buffer);
            return 0;
          }
        }
      }
    } else {
      if (SDDS_source->layout.column_definition[i].type != SDDS_target->layout.column_definition[target_index].type) {
        sprintf(buffer, "Unable to copy columns---inconsistent data types for %s (SDDS_CopyRowsOfInterest)", SDDS_source->layout.column_definition[i].name);
        SDDS_SetError(buffer);
        return (0);
      }
      for (k = 0; k < roi; k++) {
        if (((char **)SDDS_target->data[target_index])[k])
          free(((char **)SDDS_target->data[target_index])[k]);
        if (!SDDS_CopyString(&((char **)SDDS_target->data[target_index])[k], ((char **)SDDS_source->data[i])[rowList[k]])) {
          SDDS_SetError("Unable to copy rows (SDDS_CopyRowsOfInterest)");
          return (0);
        }
      }
    }
    SDDS_target->column_flag[target_index] = 1;
    SDDS_target->column_order[target_index] = target_index;
  }
  free(rowList);
  SDDS_target->n_rows = roi;
  if (SDDS_target->row_flag)
    for (i = 0; i < SDDS_target->n_rows; i++)
      SDDS_target->row_flag[i] = 1;
 
  return (1);
}

SDDS_CopyString()

epicsShareFuncSDDS int32_t SDDS_CopyString ( char ** target, const char * source )

extern

Copies a source string to a target string with memory allocation.

This function allocates memory for the target string and copies the contents of the source string into it. If the source string is NULL, the target string is set to NULL.

Parameters

[out]	target	Pointer to a char* variable where the copied string will be stored. Memory is allocated within this function and should be freed by the caller to avoid memory leaks.
[in]	source	The source string to be copied. If NULL, the target is set to NULL.

Returns

Returns 1 on successful copy and memory allocation. Returns 0 on error (e.g., memory allocation failure).

Note

The caller is responsible for freeing the memory allocated for the target string.

See also

SDDS_Free

SDDS_Malloc

Definition at line 922 of file SDDS_utils.c.

                                                           {
  if (!source)
    *target = NULL;
  else {
    if (!(*target = SDDS_Malloc(sizeof(**target) * (strlen(source) + 1))))
      return (0);
    strcpy(*target, source);
  }
  return (1);
}

SDDS_CopyStringArray()

epicsShareFuncSDDS int32_t SDDS_CopyStringArray ( char ** target, char ** source, int64_t n_strings )

extern

Copies an array of strings from source to target.

This function duplicates each string from the source array into the target array. It handles memory allocation for each individual string using SDDS_CopyString.

Parameters

[in]	target	Pointer to the destination array of strings where the copied strings will be stored.
[in]	source	Pointer to the source array of strings to be copied.
[in]	n_strings	The number of strings to copy from the source to the target.

Returns

• Returns 1 on successful copying of all strings.
• Returns 0 if either source or target is NULL, or if any string copy operation fails.

Note

• The caller is responsible for ensuring that the target array has sufficient space allocated.
• In case of failure, partially copied strings may remain in the target array.

See also

SDDS_CopyString

SDDS_Malloc

Definition at line 2903 of file SDDS_utils.c.

                                                                              {
  if (!source || !target)
    return (0);
  while (n_strings--) {
    if (!SDDS_CopyString(target + n_strings, source[n_strings]))
      return (0);
  }
  return (1);
}

SDDS_CountColumnsOfInterest()

epicsShareFuncSDDS int32_t SDDS_CountColumnsOfInterest ( SDDS_DATASET * SDDS_dataset )

extern

Counts the number of columns marked as "of interest" in the current data table.

This function returns the total number of columns that have been flagged as "of interest" based on their acceptance flags.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the data set.

Returns

• Non-negative integer representing the number of columns marked as "of interest".
• -1 if the dataset is invalid.

See also

SDDS_CountRowsOfInterest, SDDS_SetColumnFlags, SDDS_GetColumnFlags

Definition at line 342 of file SDDS_extract.c.

                                                                {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_CountRowsOfInterest"))
    return (-1);
  return (SDDS_dataset->n_of_interest);
}

SDDS_CountRowsOfInterest()

epicsShareFuncSDDS int64_t SDDS_CountRowsOfInterest ( SDDS_DATASET * SDDS_dataset )

extern

Counts the number of rows marked as "of interest" in the current data table.

This function iterates through the row acceptance flags and tallies the number of rows that are flagged as "of interest" (non-zero).

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the data set.

Returns

• Number of rows with non-zero acceptance flags.
• -1 on error (e.g., invalid dataset or tabular data).

Note

Ensure that the dataset contains tabular data before invoking this function.

See also

SDDS_SetRowFlags, SDDS_GetRowFlags, SDDS_GetRowFlag

Definition at line 364 of file SDDS_extract.c.

                                                             {
  int64_t n_rows, i;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_CountRowsOfInterest"))
    return (-1);
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_CountRowsOfInterest"))
    return (-1);
  if (!SDDS_dataset->layout.n_columns)
    return 0;
  for (i = n_rows = 0; i < SDDS_dataset->n_rows; i++) {
    if (SDDS_dataset->row_flag[i])
      n_rows += 1;
  }
  return (n_rows);
}

SDDS_CreateEmptyDataset()

epicsShareFuncSDDS SDDS_DATASET * SDDS_CreateEmptyDataset ( void )

extern

Creates an empty SDDS dataset.

This function allocates and initializes an empty SDDS_DATASET structure. The returned dataset can then be configured and populated with columns, parameters, and arrays as needed.

Returns

• Pointer to the newly created SDDS_DATASET structure.
• NULL if memory allocation fails.

Note

• The caller is responsible for initializing the dataset's layout and other necessary fields before use.
• Ensure that the returned dataset is properly freed using appropriate memory deallocation functions to prevent memory leaks.

Warning

• Failing to initialize the dataset after creation may lead to undefined behavior when performing operations on it.
• Always check if the returned pointer is not NULL before using it.

See also

SDDS_FreeDataset, SDDS_InitLayout

Definition at line 5719 of file SDDS_utils.c.

                                            {
  SDDS_DATASET *dataset;
  dataset = malloc(sizeof(SDDS_DATASET));
  return dataset;
}

SDDS_CreateRpnArray()

epicsShareFuncSDDS int64_t SDDS_CreateRpnArray ( char * name )

extern

Stub function for creating RPN arrays when RPN_SUPPORT is not enabled.

Parameters

name	Name of the RPN array.

Returns

Always returns 1.

Definition at line 835 of file SDDS_rpn.c.

                                        {
  return (1);
}

SDDS_CreateRpnMemory()

epicsShareFuncSDDS int64_t SDDS_CreateRpnMemory ( const char * name, short is_string )

extern

Stub function for creating RPN memory when RPN_SUPPORT is not enabled.

Parameters

name	Name of the RPN memory.
is_string	Flag indicating if the memory is for string data.

Returns

Always returns 1.

Definition at line 825 of file SDDS_rpn.c.

                                                                {
  return (1);
}

SDDS_CutOutComments()

epicsShareFuncSDDS void SDDS_CutOutComments ( SDDS_DATASET * SDDS_dataset, char * s, char cc )

extern

Removes comments from a string based on a specified comment character.

This function processes a string s, removing any content that follows the comment character cc. It also handles special comment lines that start with !# by parsing them using SDDS_ParseSpecialComments. The function ensures that quoted sections within the string are preserved and not mistakenly identified as comments.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure used for processing special comments.
[in,out]	s	Pointer to the character array containing the string to process. The string will be modified in place.
[in]	cc	The comment character indicating the start of a comment.

Note

If the first character of the string is the comment character, the entire line is treated as a comment. Otherwise, only the portion of the string following the first unescaped comment character is removed.

See also

SDDS_ParseSpecialComments

Definition at line 1746 of file SDDS_utils.c.

                                                                       {
  int32_t length, hasNewline;
  char *s0;
 
  if (!cc || !s)
    return;
 
  hasNewline = 0;
  length = strlen(s);
  if (s[length - 1] == '\n')
    hasNewline = 1;
 
  if (*s == cc) {
    /* check for special information */
    if (*(s + 1) == '#')
      SDDS_ParseSpecialComments(SDDS_dataset, s + 2);
    *s = 0;
    return;
  }
  s0 = s;
  while (*s) {
    if ((*s == '"') && (s == s0 || *(s - 1) != '\\')) {
      while (*++s && (*s != '"' || *(s - 1) == '\\'))
        ;
      if (!*s)
        return;
      s++;
      continue;
    }
    if (*s == cc) {
      if (s != s0 && *(s - 1) == '\\')
        strcpy_ss(s - 1, s);
      else {
        if (hasNewline) {
          *s = '\n';
          *(s + 1) = 0;
        } else
          *s = 0;
        return;
      }
    }
    s++;
  }
}

SDDS_DeferSavingLayout()

epicsShareFuncSDDS void SDDS_DeferSavingLayout ( SDDS_DATASET * SDDS_dataset, int32_t mode )

extern

Sets the flag to defer or resume saving the layout of an SDDS_DATASET.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure.
mode	Non-zero value to defer saving the layout; zero to resume saving.

Definition at line 603 of file SDDS_copy.c.

                                                                      {
  SDDS_dataset->deferSavingLayout = mode;
}

SDDS_DefineArray()

epicsShareFuncSDDS int32_t SDDS_DefineArray ( SDDS_DATASET * SDDS_dataset, const char * name, const char * symbol, const char * units, const char * description, const char * format_string, int32_t type, int32_t field_length, int32_t dimensions, const char * group_name )

extern

Defines a data array within the SDDS dataset.

This function processes the definition of a data array in the SDDS dataset. It allows the user to specify the array's name, symbol, units, description, format string, data type, field length, number of dimensions, and associated group name. The function ensures that the array name is valid and unique within the dataset before defining it.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the array. This name must be unique within the dataset.
[in]	symbol	A NULL-terminated string specifying the symbol for the array. Pass NULL if no symbol is desired.
[in]	units	A NULL-terminated string specifying the units of the array. Pass NULL if no units are desired.
[in]	description	A NULL-terminated string providing a description of the array. Pass NULL if no description is desired.
[in]	format_string	A NULL-terminated string specifying the printf-style format for ASCII output. If NULL is passed, a default format is selected based on the array type.
[in]	type	An integer representing the data type of the array. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	field_length	An integer specifying the length of the field allotted to the array for ASCII output. If set to 0, the field length is ignored. If negative, the field length is set to the absolute value, and leading and trailing white-space are eliminated for SDDS_STRING types upon reading.
[in]	dimensions	An integer specifying the number of dimensions of the array. Must be greater than 0.
[in]	group_name	A NULL-terminated string specifying the name of the array group to which this array belongs. This allows related arrays to be grouped together (e.g., parallel arrays).

Returns

• On success, returns the index of the newly defined array within the dataset.
• Returns -1 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The array name must be unique and valid.
• The specified data type must be supported by the dataset.

Postcondition

• The array is defined within the dataset with the specified attributes.
• The dataset's internal structures are updated to include the new array.

Note

• For string-type arrays, the fixed value is managed differently, and leading/trailing white-space is handled based on the field length parameter.
• The function supports multi-dimensional arrays as specified by the dimensions parameter.

Warning

• Defining an array with an invalid type, field length, or number of dimensions will result in an error.
• Attempting to define an array with a name that already exists within the dataset will result in an error.

Definition at line 1599 of file SDDS_output.c.

                                                                                                                                                                                                                                                  {
  SDDS_LAYOUT *layout;
  ARRAY_DEFINITION *definition;
  char s[SDDS_MAXLINE];
  SORTED_INDEX *new_indexed_array;
  int32_t index, duplicate;
 
  if (!SDDS_IsValidName(name, "array"))
    return -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DefineArray"))
    return (-1);
  if (!name) {
    SDDS_SetError("NULL name not allowed for array definition");
    return (-1);
  }
  layout = &SDDS_dataset->layout;
  if (!(layout->array_definition =
          SDDS_Realloc(layout->array_definition, sizeof(*layout->array_definition) * (layout->n_arrays + 1))) ||
      !(layout->array_index = SDDS_Realloc(layout->array_index, sizeof(*layout->array_index) * (layout->n_arrays + 1))) || !(new_indexed_array = (SORTED_INDEX *)SDDS_Malloc(sizeof(*new_indexed_array)))) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineArray)");
    return (-1);
  }
 
  if (!SDDS_CopyString(&new_indexed_array->name, name))
    return -1;
  index = binaryInsert((void **)layout->array_index, layout->n_arrays, new_indexed_array, SDDS_CompareIndexedNames, &duplicate);
  if (duplicate) {
    sprintf(s, "Array %s already exists (SDDS_DefineArray)", name);
    SDDS_SetError(s);
    return (-1);
  }
  layout->array_index[index]->index = layout->n_arrays;
 
  if (!SDDS_ZeroMemory(definition = layout->array_definition + layout->n_arrays, sizeof(ARRAY_DEFINITION))) {
    SDDS_SetError("Unable to define array--can't zero memory for array definition (SDDS_DefineArray)");
    return (-1);
  }
  definition->name = new_indexed_array->name;
  if ((symbol && !SDDS_CopyString(&definition->symbol, symbol)) || (units && !SDDS_CopyString(&definition->units, units)) || (description && !SDDS_CopyString(&definition->description, description)) || (group_name && !SDDS_CopyString(&definition->group_name, group_name))) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineArray)");
    return (-1);
  }
  if (type <= 0 || type > SDDS_NUM_TYPES) {
    SDDS_SetError("Unknown data type (SDDS_DefineArray)");
    return (-1);
  }
  definition->type = type;
  if (format_string) {
    if (!SDDS_VerifyPrintfFormat(format_string, type)) {
      SDDS_SetError("Invalid format string (SDDS_DefineArray)");
      return (-1);
    }
    if (!SDDS_CopyString(&definition->format_string, format_string)) {
      SDDS_SetError("Memory allocation failure (SDDS_DefineArray)");
      return (-1);
    }
  }
  if ((definition->field_length = field_length) < 0 && type != SDDS_STRING) {
    SDDS_SetError("Invalid field length (SDDS_DefineArray)");
    return (-1);
  }
  if ((definition->dimensions = dimensions) < 1) {
    SDDS_SetError("Invalid number of dimensions for array (SDDS_DefineArray)");
    return (-1);
  }
  layout->n_arrays += 1;
  return (layout->n_arrays - 1);
}

SDDS_DefineAssociate()

epicsShareFuncSDDS int32_t SDDS_DefineAssociate ( SDDS_DATASET * SDDS_dataset, const char * name, const char * filename, const char * path, const char * description, const char * contents, int32_t sdds )

extern

Defines an associate for the SDDS dataset.

This function defines an associate for the SDDS dataset, allowing the association of additional files or data with the primary dataset. Associates can provide supplementary information or link related datasets together. The function sets up the necessary attributes such as name, filename, path, description, contents, and SDDS flag to describe the associate.

Note: This function is NOT USED in the current implementation and will always return 0 unless compiled with RW_ASSOCIATES defined.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the associate. This name must be unique within the dataset.
[in]	filename	A NULL-terminated string specifying the filename of the associate. Must be a valid filename.
[in]	path	A NULL-terminated string specifying the path to the associate. Pass NULL if no path is desired.
[in]	description	A NULL-terminated string providing a description of the associate. Pass NULL if no description is desired.
[in]	contents	A NULL-terminated string detailing the contents of the associate. Pass NULL if no contents are desired.
[in]	sdds	An integer flag indicating the type of associate. Typically used to specify whether the associate is an SDDS file.

Returns

• On success, returns the index of the newly defined associate within the dataset.
• Returns a negative value on failure, with an error message set internally.
• Returns 0 if RW_ASSOCIATES is not defined.

Precondition

• The dataset must be initialized and configured for output.
• RW_ASSOCIATES must be defined during compilation to use this feature.
• The associate name and filename must be unique and valid.

Postcondition

• The associate is defined within the dataset with the specified attributes.
• The dataset's internal structures are updated to include the new associate.

Note

• Associates provide a mechanism to link additional data or files to the primary SDDS dataset.
• Properly defining associates can enhance data organization and accessibility.

Warning

• Defining an associate with an invalid type, name, or filename will result in an error.
• Attempting to define an associate with a name that already exists within the dataset will result in an error.
• Ensure that the filename and path (if provided) are valid and accessible.

Definition at line 2173 of file SDDS_output.c.

                                                                                                                                                                                {
 
#if RW_ASSOCIATES == 0
  return 0;
#else
  SDDS_LAYOUT *layout;
  ASSOCIATE_DEFINITION *definition;
  char s[SDDS_MAXLINE];
  if (!SDDS_IsValidName(name, "associate"))
    return -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DefineAssociate"))
    return (-1);
  layout = &SDDS_dataset->layout;
  if (!(layout->associate_definition = SDDS_Realloc(layout->associate_definition, sizeof(*layout->associate_definition) * (layout->n_associates + 1)))) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineAssociate)");
    return (-1);
  }
  if (!name) {
    SDDS_SetError("NULL name not allowed for associate file (SDDS_DefineAssociate)");
    return (-1);
  }
  if (!filename) {
    SDDS_SetError("NULL filename not allowed for associate file (SDDS_DefineAssociate)");
    return (-1);
  }
  if (SDDS_GetAssociateIndex(SDDS_dataset, name) >= 0) {
    sprintf(s, "Associate with name %s already exists (SDDS_DefineAssociate)", name);
    SDDS_SetError(s);
    return (-1);
  }
  if (!SDDS_ZeroMemory(definition = layout->associate_definition + layout->n_associates, sizeof(ASSOCIATE_DEFINITION))) {
    SDDS_SetError("Unable to define associate--can't zero memory for associate (SDDS_DefineAssociate)");
    return (-1);
  }
 
  if (!SDDS_CopyString(&definition->name, name)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineAssociate)");
    return (-1);
  }
  if (!SDDS_CopyString(&definition->filename, filename)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineAssociate)");
    return (-1);
  }
  if (path && !SDDS_CopyString(&definition->path, path)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineAssociate)");
    return (-1);
  }
  if (contents && !SDDS_CopyString(&definition->contents, contents)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineAssociate)");
    return (-1);
  }
  if (description && !SDDS_CopyString(&definition->description, description)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineAssociate)");
    return (-1);
  }
  definition->sdds = sdds;
  layout->n_associates += 1;
  return (layout->n_associates - 1);
#endif
}

SDDS_DefineColumn()

epicsShareFuncSDDS int32_t SDDS_DefineColumn ( SDDS_DATASET * SDDS_dataset, const char * name, const char * symbol, const char * units, const char * description, const char * format_string, int32_t type, int32_t field_length )

extern

Defines a data column within the SDDS dataset.

This function processes the definition of a data column in the SDDS dataset. It allows the user to specify the column's name, symbol, units, description, format string, data type, and field length. The function ensures that the column name is valid and unique within the dataset before defining it.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the column. This name must be unique within the dataset.
[in]	symbol	A NULL-terminated string specifying the symbol for the column. Pass NULL if no symbol is desired.
[in]	units	A NULL-terminated string specifying the units of the column. Pass NULL if no units are desired.
[in]	description	A NULL-terminated string providing a description of the column. Pass NULL if no description is desired.
[in]	format_string	A NULL-terminated string specifying the printf-style format for ASCII output. If NULL is passed, a default format is selected based on the column type.
[in]	type	An integer representing the data type of the column. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	field_length	An integer specifying the length of the field allotted to the column for ASCII output. If set to 0, the field length is ignored. If negative, the field length is set to the absolute value, and leading and trailing white-space are eliminated for SDDS_STRING types upon reading.

Returns

• On success, returns the index of the newly defined column within the dataset.
• Returns -1 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The column name must be unique and valid.
• The specified data type must be supported by the dataset.

Postcondition

• The column is defined within the dataset with the specified attributes.
• The dataset's internal structures are updated to include the new column.
• If rows have already been allocated, the data arrays are resized to accommodate the new column.

Note

• For string-type columns, the fixed value is managed differently, and leading/trailing white-space is handled based on the field length parameter.
• The function ensures that data arrays are appropriately resized if data has already been allocated.

Warning

• Defining a column with an invalid type, field length, or name will result in an error.
• Attempting to define a column with a name that already exists within the dataset will result in an error.
• Memory allocation failures during the definition process will lead to an error.

Definition at line 1716 of file SDDS_output.c.

                                                                                                                                                                                                       {
  SDDS_LAYOUT *layout;
  COLUMN_DEFINITION *definition;
  char s[SDDS_MAXLINE];
  SORTED_INDEX *new_indexed_column;
  int32_t index;
  int32_t duplicate;
 
  if (!SDDS_IsValidName(name, "column"))
    return -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DefineColumn"))
    return (-1);
  if (!name) {
    SDDS_SetError("NULL name not allowed for column definition");
    return (-1);
  }
  layout = &SDDS_dataset->layout;
  if (!(layout->column_definition =
          SDDS_Realloc(layout->column_definition, sizeof(*layout->column_definition) * (layout->n_columns + 1))) ||
      !(layout->column_index = SDDS_Realloc(layout->column_index, sizeof(*layout->column_index) * (layout->n_columns + 1))) || !(new_indexed_column = (SORTED_INDEX *)SDDS_Malloc(sizeof(*new_indexed_column)))) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineColumn)");
    return (-1);
  }
  if (!SDDS_CopyString(&new_indexed_column->name, name))
    return -1;
  index = binaryInsert((void **)layout->column_index, layout->n_columns, new_indexed_column, SDDS_CompareIndexedNames, &duplicate);
  if (duplicate) {
    sprintf(s, "Column %s already exists (SDDS_DefineColumn)", name);
    SDDS_SetError(s);
    return (-1);
  }
  layout->column_index[index]->index = layout->n_columns;
  if (!SDDS_ZeroMemory(definition = layout->column_definition + layout->n_columns, sizeof(COLUMN_DEFINITION))) {
    SDDS_SetError("Unable to define column--can't zero memory for column definition (SDDS_DefineColumn)");
    return (-1);
  }
  definition->name = new_indexed_column->name;
  if (symbol && !SDDS_CopyString(&definition->symbol, symbol)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineColumn)");
    return (-1);
  }
  if (units && !SDDS_CopyString(&definition->units, units)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineColumn)");
    return (-1);
  }
  if (description && !SDDS_CopyString(&definition->description, description)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineColumn)");
    return (-1);
  }
  if (type <= 0 || type > SDDS_NUM_TYPES) {
    SDDS_SetError("Unknown data type (SDDS_DefineColumn)");
    return (-1);
  }
  definition->type = type;
  if (format_string) {
    if (!SDDS_VerifyPrintfFormat(format_string, type)) {
      SDDS_SetError("Invalid format string (SDDS_DefineColumn)");
      return (-1);
    }
    if (!SDDS_CopyString(&definition->format_string, format_string)) {
      SDDS_SetError("Memory allocation failure (SDDS_DefineColumn)");
      return (-1);
    }
  }
  if ((definition->field_length = field_length) < 0 && type != SDDS_STRING) {
    SDDS_SetError("Invalid field length (SDDS_DefineColumn)");
    return (-1);
  }
 
  if (SDDS_dataset->n_rows_allocated) {
    if (!SDDS_dataset->data) {
      SDDS_SetError("data array NULL but rows have been allocated! (SDDS_DefineColumn)");
      return (-1);
    }
    /* data already present--must resize data and parameter memory */
    if (!(SDDS_dataset->data = SDDS_Realloc(SDDS_dataset->data, sizeof(*SDDS_dataset->data) * (layout->n_columns + 1))) || !(SDDS_dataset->data[layout->n_columns] = calloc(SDDS_dataset->n_rows_allocated, SDDS_type_size[type - 1]))) {
      SDDS_SetError("Memory allocation failure (SDDS_DefineColumn)");
      return (-1);
    }
  }
 
  /* not part of output: */
  definition->definition_mode = SDDS_NORMAL_DEFINITION;
  if (type == SDDS_STRING)
    definition->memory_number = SDDS_CreateRpnMemory(name, 1);
  else {
    definition->memory_number = SDDS_CreateRpnMemory(name, 0);
  }
  sprintf(s, "&%s", name);
  definition->pointer_number = SDDS_CreateRpnArray(s);
 
  layout->n_columns += 1;
  return (layout->n_columns - 1);
}

SDDS_DefineColumnLikeArray()

epicsShareFuncSDDS int32_t SDDS_DefineColumnLikeArray ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Defines a column in the target dataset based on an array definition from the source dataset.

This function creates a column in the target SDDS dataset with properties matching those of a specified array in the source dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the array in the source dataset whose definition is to be used.
newName	The name of the column in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 302 of file SDDS_transfer.c.

                                                                                                          {
  ARRAY_DEFINITION *arrayDef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to define column--NULL or blank name passed (SDDS_DefineColumnLikeArray)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(arrayDef = SDDS_GetArrayDefinition(source, name))) {
    SDDS_SetError("Unable to define column--unknown array named (SDDS_DefineColumnLikeArray)");
    return 0;
  }
  if (SDDS_GetColumnIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to define column--already exists (SDDS_DefineColumnLikeArray)");
    return 0;
  }
  if (SDDS_DefineColumn(target, newName, arrayDef->symbol, arrayDef->units, arrayDef->description, arrayDef->format_string, arrayDef->type, 0) < 0) {
    SDDS_FreeArrayDefinition(arrayDef);
    SDDS_SetError("Unable to define column--call to define column failed (SDDS_DefineColumnLikeArray)");
    return 0;
  }
  SDDS_FreeArrayDefinition(arrayDef);
  return 1;
}

SDDS_DefineColumnLikeParameter()

epicsShareFuncSDDS int32_t SDDS_DefineColumnLikeParameter ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Defines a column in the target dataset based on a parameter definition from the source dataset.

This function creates a column in the target SDDS dataset with properties matching those of a specified parameter in the source dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the parameter in the source dataset whose definition is to be used.
newName	The name of the column in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 264 of file SDDS_transfer.c.

                                                                                                              {
  PARAMETER_DEFINITION *pardef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to define column--NULL or blank name passed (SDDS_DefineColumnLikeParameter)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(pardef = SDDS_GetParameterDefinition(source, name))) {
    SDDS_SetError("Unable to define column--unknown parameter named (SDDS_DefineColumnLikeParameter)");
    return 0;
  }
  if (SDDS_GetColumnIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to define column--already exists (SDDS_DefineColumnLikeParameter)");
    return 0;
  }
  if (SDDS_DefineColumn(target, newName, pardef->symbol, pardef->units, pardef->description, pardef->format_string, pardef->type, 0) < 0) {
    SDDS_FreeParameterDefinition(pardef);
    SDDS_SetError("Unable to define column--call to define column failed (SDDS_DefineColumnLikeParameter)");
    return 0;
  }
  SDDS_FreeParameterDefinition(pardef);
  return 1;
}

SDDS_DefineParameter()

epicsShareFuncSDDS int32_t SDDS_DefineParameter ( SDDS_DATASET * SDDS_dataset, const char * name, const char * symbol, const char * units, const char * description, const char * format_string, int32_t type, char * fixed_value )

extern

Defines a data parameter with a fixed string value.

This function processes the definition of a data parameter within the SDDS dataset. It allows the specification of a fixed string value for the parameter, which remains constant across all data entries. The function validates the parameter name, type, and format string before defining the parameter in the dataset.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the parameter. This name must be unique within the dataset.
[in]	symbol	A NULL-terminated string specifying the symbol for the parameter. Pass NULL if no symbol is desired.
[in]	units	A NULL-terminated string specifying the units of the parameter. Pass NULL if no units are desired.
[in]	description	A NULL-terminated string providing a description of the parameter. Pass NULL if no description is desired.
[in]	format_string	A NULL-terminated string specifying the printf-style format for ASCII output. If NULL is passed, a default format is selected based on the parameter type.
[in]	type	An integer representing the data type of the parameter. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	fixed_value	A NULL-terminated string specifying the fixed value of the parameter. For non-string types, this string should be formatted appropriately using functions like sprintf.

Returns

• On success, returns the index of the newly defined parameter within the dataset.
• Returns -1 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The parameter name must be unique and valid.
• The fixed value must be a valid string representation for the specified parameter type.

Postcondition

• The parameter is defined within the dataset with the specified attributes and fixed value.
• The dataset's internal structures are updated to include the new parameter.

Note

• For numerical parameter types, the fixed value string should represent the numerical value correctly.
• The function internally handles the conversion of the fixed value string to the appropriate type based on the parameter's data type.

Warning

• Defining a parameter with an invalid type or format string will result in an error.
• Passing an improperly formatted fixed value string for the specified type may lead to unexpected behavior.

Definition at line 1473 of file SDDS_output.c.

                                                                                                                                                                                                       {
  SDDS_LAYOUT *layout;
  PARAMETER_DEFINITION *definition;
  char s[SDDS_MAXLINE];
  SORTED_INDEX *new_indexed_parameter;
  int32_t index, duplicate;
 
  if (!SDDS_IsValidName(name, "parameter"))
    return -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DefineParameter"))
    return (-1);
  if (!name) {
    SDDS_SetError("NULL name not allowed for parameter definition");
    return (-1);
  }
  layout = &SDDS_dataset->layout;
  if (!(layout->parameter_definition =
          SDDS_Realloc(layout->parameter_definition, sizeof(*layout->parameter_definition) * (layout->n_parameters + 1))) ||
      !(layout->parameter_index = SDDS_Realloc(layout->parameter_index, sizeof(*layout->parameter_index) * (layout->n_parameters + 1))) || !(new_indexed_parameter = (SORTED_INDEX *)SDDS_Malloc(sizeof(*new_indexed_parameter)))) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineParameter)");
    return (-1);
  }
  if (!SDDS_CopyString(&new_indexed_parameter->name, name))
    return -1;
  index = binaryInsert((void **)layout->parameter_index, layout->n_parameters, new_indexed_parameter, SDDS_CompareIndexedNames, &duplicate);
  if (duplicate) {
    sprintf(s, "Parameter %s already exists (SDDS_DefineParameter)", name);
    SDDS_SetError(s);
    return (-1);
  }
  layout->parameter_index[index]->index = layout->n_parameters;
 
  if (!SDDS_ZeroMemory(definition = layout->parameter_definition + layout->n_parameters, sizeof(PARAMETER_DEFINITION))) {
    SDDS_SetError("Unable to define parameter--can't zero memory for parameter definition (SDDS_DefineParameter)");
    return (-1);
  }
  definition->name = new_indexed_parameter->name;
  if (symbol && !SDDS_CopyString(&definition->symbol, symbol)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineParameter)");
    return (-1);
  }
  if (units && !SDDS_CopyString(&definition->units, units)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineParameter)");
    return (-1);
  }
  if (description && !SDDS_CopyString(&definition->description, description)) {
    SDDS_SetError("Memory allocation failure (SDDS_DefineParameter)");
    return (-1);
  }
  if (type <= 0 || type > SDDS_NUM_TYPES) {
    SDDS_SetError("Unknown data type (SDDS_DefineParameter)");
    return (-1);
  }
  definition->type = type;
  if (format_string) {
    if (!SDDS_VerifyPrintfFormat(format_string, type)) {
      SDDS_SetError("Invalid format string (SDDS_DefineParameter)");
      return (-1);
    }
    if (!SDDS_CopyString(&definition->format_string, format_string)) {
      SDDS_SetError("Memory allocation failure (SDDS_DefineParameter)");
      return (-1);
    }
  }
  if (fixed_value && !SDDS_CopyString(&(definition->fixed_value), fixed_value)) {
    SDDS_SetError("Couldn't copy fixed_value string (SDDS_DefineParameter)");
    return (-1);
  }
  definition->definition_mode = SDDS_NORMAL_DEFINITION;
  if (type == SDDS_STRING)
    definition->memory_number = SDDS_CreateRpnMemory(name, 1);
  else
    definition->memory_number = SDDS_CreateRpnMemory(name, 0);
  layout->n_parameters += 1;
  return (layout->n_parameters - 1);
}

SDDS_DefineParameter1()

epicsShareFuncSDDS int32_t SDDS_DefineParameter1 ( SDDS_DATASET * SDDS_dataset, const char * name, const char * symbol, const char * units, const char * description, const char * format_string, int32_t type, void * fixed_value )

extern

Defines a data parameter with a fixed numerical value.

This function processes the definition of a data parameter within the SDDS dataset. It allows the specification of a fixed numerical value for the parameter, which remains constant across all data entries. The function validates the parameter name, type, and format string before defining the parameter in the dataset.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the parameter. This name must be unique within the dataset.
[in]	symbol	A NULL-terminated string specifying the symbol for the parameter. Pass NULL if no symbol is desired.
[in]	units	A NULL-terminated string specifying the units of the parameter. Pass NULL if no units are desired.
[in]	description	A NULL-terminated string providing a description of the parameter. Pass NULL if no description is desired.
[in]	format_string	A NULL-terminated string specifying the printf-style format for ASCII output. If NULL is passed, a default format is selected based on the parameter type.
[in]	type	An integer representing the data type of the parameter. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	fixed_value	A pointer to the numerical value that remains constant for this parameter across all data entries. This value is used to initialize the parameter's fixed value.

Returns

• On success, returns the index of the newly defined parameter within the dataset.
• Returns -1 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The parameter name must be unique and valid.
• The fixed value must be non-NULL for numerical types and should be prepared appropriately.

Postcondition

• The parameter is defined within the dataset with the specified attributes and fixed value.
• The dataset's internal structures are updated to include the new parameter.

Note

• For string-type parameters, the fixed value should be a NULL-terminated string.
• The function internally converts the fixed numerical value to a string representation if the parameter type is not SDDS_STRING.

Warning

• Defining a parameter with an invalid type or format string will result in an error.
• Passing a NULL fixed value for non-string types will result in an error.

Definition at line 1408 of file SDDS_output.c.

                                                                                                                                                                                                        {
  char buffer[SDDS_MAXLINE];
  if (!SDDS_IsValidName(name, "parameter"))
    return -1;
  if (!fixed_value || type == SDDS_STRING)
    return SDDS_DefineParameter(SDDS_dataset, name, symbol, units, description, format_string, type, fixed_value);
  if (type <= 0 || type > SDDS_NUM_TYPES) {
    SDDS_SetError("Unknown data type (SDDS_DefineParameter1)");
    return (-1);
  }
  buffer[SDDS_MAXLINE - 1] = 0;
  if (!SDDS_SprintTypedValue(fixed_value, 0, type, format_string, buffer, 0) || buffer[SDDS_MAXLINE - 1] != 0) {
    SDDS_SetError("Unable to define fixed value for parameter (SDDS_DefineParameter1)");
    return (-1);
  }
  return SDDS_DefineParameter(SDDS_dataset, name, symbol, units, description, format_string, type, buffer);
}

SDDS_DefineParameterLikeArray()

epicsShareFuncSDDS int32_t SDDS_DefineParameterLikeArray ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Defines a parameter in the target dataset based on an array definition from the source dataset.

This function creates a parameter in the target SDDS dataset with properties matching those of a specified array in the source dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the array in the source dataset whose definition is to be used.
newName	The name of the parameter in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 226 of file SDDS_transfer.c.

                                                                                                             {
  ARRAY_DEFINITION *arrayDef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to define parameter--NULL or blank name passed (SDDS_DefineParameterLikeArray)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(arrayDef = SDDS_GetArrayDefinition(source, name))) {
    SDDS_SetError("Unable to define parameter--unknown array named (SDDS_DefineParameterLikeArray)");
    return 0;
  }
  if (SDDS_GetParameterIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to define parameter--already exists (SDDS_DefineParameterLikeArray)");
    return 0;
  }
  if (SDDS_DefineParameter(target, newName, arrayDef->symbol, arrayDef->units, arrayDef->description, arrayDef->format_string, arrayDef->type, NULL) < 0) {
    SDDS_FreeArrayDefinition(arrayDef);
    SDDS_SetError("Unable to define parameter--call to define parameter failed (SDDS_DefineParameterLikeArray)");
    return 0;
  }
  SDDS_FreeArrayDefinition(arrayDef);
  return 1;
}

SDDS_DefineParameterLikeColumn()

epicsShareFuncSDDS int32_t SDDS_DefineParameterLikeColumn ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Defines a parameter in the target dataset based on a column definition from the source dataset.

This function creates a parameter in the target SDDS dataset with properties matching those of a specified column in the source dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the column in the source dataset whose definition is to be used.
newName	The name of the parameter in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 188 of file SDDS_transfer.c.

                                                                                                              {
  COLUMN_DEFINITION *coldef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to define parameter--NULL or blank name passed (SDDS_DefineParameterLikeColumn)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(coldef = SDDS_GetColumnDefinition(source, name))) {
    SDDS_SetError("Unable to define parameter--unknown column named (SDDS_DefineParameterLikeColumn)");
    return 0;
  }
  if (SDDS_GetParameterIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to define parameter--already exists (SDDS_DefineParameterLikeColumn)");
    return 0;
  }
  if (SDDS_DefineParameter(target, newName, coldef->symbol, coldef->units, coldef->description, coldef->format_string, coldef->type, NULL) < 0) {
    SDDS_FreeColumnDefinition(coldef);
    SDDS_SetError("Unable to define parameter--call to define parameter failed (SDDS_DefineParameterLikeColumn)");
    return 0;
  }
  SDDS_FreeColumnDefinition(coldef);
  return 1;
}

SDDS_DefineSimpleColumn()

epicsShareFuncSDDS int32_t SDDS_DefineSimpleColumn ( SDDS_DATASET * SDDS_dataset, const char * name, const char * unit, int32_t type )

extern

Defines a simple data column within the SDDS dataset.

This function provides a simplified interface for defining a data column in the SDDS dataset. It allows the user to specify only the column's name, units, and data type, while omitting optional parameters such as symbol, description, format string, and field length. Internally, it calls SDDS_DefineColumn with default values for the omitted parameters.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the column. This name must be unique within the dataset.
[in]	unit	A NULL-terminated string specifying the units of the column. Pass NULL if no units are desired.
[in]	type	An integer representing the data type of the column. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING

Returns

• 1 on successful definition of the column.
• 0 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The column name must be unique and valid.

Postcondition

• The column is defined within the dataset with the specified name, units, and type.
• The dataset's internal structures are updated to include the new column.

Note

• This function is intended for scenarios where only basic column attributes are needed.
• Optional parameters such as symbol, description, format string, and field length are set to default values.

Warning

• Defining a column with an invalid type or name will result in an error.
• Attempting to define a column with a name that already exists within the dataset will result in an error.

Definition at line 1853 of file SDDS_output.c.

                                                                                                              {
  if (SDDS_DefineColumn(SDDS_dataset, name, NULL, unit, NULL, NULL, type, 0) < 0)
    return 0;
  return (1);
}

SDDS_DefineSimpleColumns()

epicsShareFuncSDDS int32_t SDDS_DefineSimpleColumns ( SDDS_DATASET * SDDS_dataset, int32_t number, char ** name, char ** unit, int32_t type )

extern

Defines multiple simple data columns of the same data type within the SDDS dataset.

This function provides a streamlined way to define multiple data columns in the SDDS dataset that share the same data type. It allows the user to specify the names and units of the columns, while omitting optional attributes such as symbol, description, format string, and field length. Internally, it calls SDDS_DefineColumn for each column with default values for the omitted parameters.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	number	The number of columns to define. Must be greater than or equal to 0.
[in]	name	An array of NULL-terminated strings specifying the names of the columns. Each name must be unique within the dataset.
[in]	unit	An array of NULL-terminated strings specifying the units of the columns. Pass NULL for elements where no units are desired.
[in]	type	An integer representing the data type for all the columns. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING

Returns

• 1 on successful definition of all specified columns.
• 0 on failure to define any of the columns, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The name array must contain unique and valid names for each column.
• The type must be a supported data type.

Postcondition

• All specified columns are defined within the dataset with the provided names and units.
• The dataset's internal structures are updated to include the new columns.

Note

• Passing number as 0 results in no action and returns success.
• This function is optimized for defining multiple columns of the same type, enhancing code readability and efficiency.

Warning

• Defining a column with an invalid type or name will result in an error.
• Attempting to define a column with a name that already exists within the dataset will result in an error.
• Ensure that the name and unit arrays are properly allocated and contain valid strings.

Definition at line 1952 of file SDDS_output.c.

                                                                                                                     {
  int32_t i;
  if (!number)
    return (1);
  if (!name)
    return 0;
  for (i = 0; i < number; i++)
    if (SDDS_DefineColumn(SDDS_dataset, name[i], NULL, unit ? unit[i] : NULL, NULL, NULL, type, 0) < 0)
      return 0;
  return (1);
}

SDDS_DefineSimpleParameter()

epicsShareFuncSDDS int32_t SDDS_DefineSimpleParameter ( SDDS_DATASET * SDDS_dataset, const char * name, const char * unit, int32_t type )

extern

Defines a simple data parameter within the SDDS dataset.

This function provides a simplified interface for defining a data parameter in the SDDS dataset. It allows the user to specify only the parameter's name, units, and data type, while omitting optional attributes such as symbol, description, format string, and fixed value. Internally, it calls SDDS_DefineParameter with default values for the omitted parameters.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A NULL-terminated string specifying the name of the parameter. This name must be unique within the dataset.
[in]	unit	A NULL-terminated string specifying the units of the parameter. Pass NULL if no units are desired.
[in]	type	An integer representing the data type of the parameter. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING

Returns

• 1 on successful definition of the parameter.
• 0 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The parameter name must be unique and valid.

Postcondition

• The parameter is defined within the dataset with the specified name, units, and type.
• The dataset's internal structures are updated to include the new parameter.

Note

• This function is intended for scenarios where only basic parameter attributes are needed.
• Optional parameters such as symbol, description, format string, and fixed value are set to default values.

Warning

• Defining a parameter with an invalid type or name will result in an error.
• Attempting to define a parameter with a name that already exists within the dataset will result in an error.

Definition at line 1901 of file SDDS_output.c.

                                                                                                                 {
  if (SDDS_DefineParameter(SDDS_dataset, name, NULL, unit, NULL, NULL, type, NULL) < 0)
    return 0;
  return (1);
}

SDDS_DefineSimpleParameters()

epicsShareFuncSDDS int32_t SDDS_DefineSimpleParameters ( SDDS_DATASET * SDDS_dataset, int32_t number, char ** name, char ** unit, int32_t type )

extern

Defines multiple simple data parameters of the same data type within the SDDS dataset.

This function provides a streamlined way to define multiple data parameters in the SDDS dataset that share the same data type. It allows the user to specify the names and units of the parameters, while omitting optional attributes such as symbol, description, format string, and fixed value. Internally, it calls SDDS_DefineParameter for each parameter with default values for the omitted parameters.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	number	The number of parameters to define. Must be greater than or equal to 0.
[in]	name	An array of NULL-terminated strings specifying the names of the parameters. Each name must be unique within the dataset.
[in]	unit	An array of NULL-terminated strings specifying the units of the parameters. Pass NULL for elements where no units are desired.
[in]	type	An integer representing the data type for all the parameters. Must be one of the following: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING

Returns

• 1 on successful definition of all specified parameters.
• 0 on failure to define any of the parameters, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The name array must contain unique and valid names for each parameter.
• The type must be a supported data type.

Postcondition

• All specified parameters are defined within the dataset with the provided names and units.
• The dataset's internal structures are updated to include the new parameters.

Note

• Passing number as 0 results in no action and returns success.
• This function is optimized for defining multiple parameters of the same type, enhancing code readability and efficiency.

Warning

• Defining a parameter with an invalid type or name will result in an error.
• Attempting to define a parameter with a name that already exists within the dataset will result in an error.
• Ensure that the name and unit arrays are properly allocated and contain valid strings.

Definition at line 2009 of file SDDS_output.c.

                                                                                                                        {
  int32_t i;
  if (!number)
    return (1);
  if (!name)
    return 0;
  for (i = 0; i < number; i++)
    if (SDDS_DefineParameter(SDDS_dataset, name[i], NULL, unit ? unit[i] : NULL, NULL, NULL, type, NULL) < 0)
      return 0;
  return (1);
}

SDDS_DeleteColumn()

epicsShareFuncSDDS int32_t SDDS_DeleteColumn ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Deletes a specified column from an SDDS dataset.

Note: This function is currently non-functional and will abort execution if called.

This function is intended to remove a column identified by column_name from the provided SDDS dataset. It handles the reordering of remaining columns and updates the dataset's layout accordingly. However, as indicated by the current implementation, the function is not operational and will terminate the program when invoked.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
column_name	A null-terminated string specifying the name of the column to be deleted.

Returns

This function does not return as it aborts execution. If it were functional, it would return 1 on success and 0 on failure.

Warning

• Currently Non-Functional: The function will terminate the program with an error message when called.

Todo

• Implement the functionality to delete a column without aborting.

See also

SDDS_DeleteUnsetColumns, SDDS_CopyColumn

Definition at line 3846 of file SDDS_extract.c.

                                                                         {
  int32_t index;
  int64_t i, j;
 
  SDDS_Bomb("SDDS_DeleteColumn is presently not functional.");
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DeleteColumn"))
    return (0);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to delete column--unrecognized column name (SDDS_DeleteColumn)");
    return (0);
  }
  for (i = index + 1; i < SDDS_dataset->layout.n_columns; i++) {
    if (!SDDS_CopyColumn(SDDS_dataset, i - 1, i)) {
      SDDS_SetError("Unable to delete column--error copying column (SDDS_DeleteColumn)");
      return (0);
    }
    for (j = 0; j < SDDS_dataset->n_of_interest; j++)
      if (SDDS_dataset->column_order[j] == index) {
        memcpy((char *)(SDDS_dataset->column_order + j), (char *)(SDDS_dataset->column_order + j + 1), sizeof(*SDDS_dataset->column_order) * (SDDS_dataset->n_of_interest - j - 1));
        SDDS_dataset->n_of_interest--;
      } else if (SDDS_dataset->column_order[j] > index)
        SDDS_dataset->column_order[j] -= 1;
  }
  if ((SDDS_dataset->layout.n_columns -= 1) == 0)
    SDDS_dataset->n_rows = 0;
  return (1);
}

SDDS_DeleteParameter()

epicsShareFuncSDDS int32_t SDDS_DeleteParameter ( SDDS_DATASET * SDDS_dataset, char * parameter_name )

extern

Deletes a specified parameter from an SDDS dataset.

This function removes a parameter identified by parameter_name from the provided SDDS dataset. It shifts all subsequent parameters up to fill the gap left by the deleted parameter and updates the dataset's parameter count accordingly.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to be deleted.

Returns

On success, returns 1. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that the parameter was successfully deleted.
0	Indicates that an error occurred (e.g., invalid dataset, unrecognized parameter name, error copying parameters).

Note

• This operation modifies the dataset by removing the specified parameter.
• It is recommended to ensure that the parameter to be deleted is not essential for further operations.

See also

SDDS_CopyParameter, SDDS_DeleteUnsetParameters

Definition at line 3979 of file SDDS_extract.c.

                                                                               {
  int32_t i, index;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DeleteParameter"))
    return (0);
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to delete parameter--unrecognized parameter name (SDDS_DeleteParameter)");
    return (0);
  }
  for (i = index + 1; i < SDDS_dataset->layout.n_parameters; i++) {
    if (!SDDS_CopyParameter(SDDS_dataset, i - 1, i)) {
      SDDS_SetError("Unable to delete parameter--error copying parameter (SDDS_DeleteParameter)");
      return (0);
    }
  }
  SDDS_dataset->layout.n_parameters -= 1;
  return (1);
}

SDDS_DeleteParameterFixedValues()

epicsShareFuncSDDS int32_t SDDS_DeleteParameterFixedValues ( SDDS_DATASET * SDDS_dataset )

extern

Deletes fixed values from all parameters in the SDDS dataset.

This function iterates through all parameters in the provided SDDS dataset and removes any fixed values associated with them. It ensures that both the current layout and the original layout of the dataset have their fixed values cleared.

Parameters

[in]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset from which fixed values will be deleted.

Returns

• 1 on successful deletion of all fixed values.
• 0 if the dataset check fails or if saving the layout fails.

Note

• The function requires that the SDDS dataset is properly initialized and that it contains parameters with fixed values.
• Both the current layout and the original layout are updated to remove fixed values.

Warning

• This operation cannot be undone. Ensure that fixed values are no longer needed before calling this function.
• Improper handling of memory allocations related to fixed values may lead to memory leaks or undefined behavior.

See also

SDDS_CheckDataset, SDDS_SaveLayout

Definition at line 4974 of file SDDS_utils.c.

                                                                    {
  int32_t i;
  SDDS_LAYOUT *layout, *orig_layout;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DeleteFixedValueParameters"))
    return 0;
  if (!SDDS_SaveLayout(SDDS_dataset))
    return 0;
  layout = &SDDS_dataset->layout;
  orig_layout = &SDDS_dataset->original_layout;
  for (i = 0; i < layout->n_parameters; i++) {
    if (layout->parameter_definition[i].fixed_value)
      free(layout->parameter_definition[i].fixed_value);
    if (orig_layout->parameter_definition[i].fixed_value && (!layout->parameter_definition[i].fixed_value || orig_layout->parameter_definition[i].fixed_value != layout->parameter_definition[i].fixed_value))
      free(orig_layout->parameter_definition[i].fixed_value);
    orig_layout->parameter_definition[i].fixed_value = NULL;
    layout->parameter_definition[i].fixed_value = NULL;
  }
  return 1;
}

SDDS_DeleteUnsetColumns()

epicsShareFuncSDDS int32_t SDDS_DeleteUnsetColumns ( SDDS_DATASET * SDDS_dataset )

extern

Deletes all columns from an SDDS dataset that are not marked as "of interest".

This function iterates through all columns in the provided SDDS dataset and removes those that have not been flagged as "of interest". It ensures that only desired columns are retained, updating the dataset's layout and column order accordingly.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

On success, returns 1. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that columns were successfully deleted.
0	Indicates that an error occurred (e.g., invalid dataset, failure to delete a column).

Note

• This operation modifies the dataset in place by removing unset columns.
• It is recommended to perform column selection before calling this function to ensure that only desired columns are retained.

See also

SDDS_SetColumnsOfInterest, SDDS_DeleteColumn, SDDS_CopyColumn

Definition at line 3894 of file SDDS_extract.c.

                                                            {
  int64_t i;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DeleteUnsetColumns"))
    return (0);
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
    if (!SDDS_dataset->column_flag[i]) {
      if (!SDDS_DeleteColumn(SDDS_dataset, SDDS_dataset->layout.column_definition[i].name))
        return (0);
      else
        i--;
    }
  return (1);
}

SDDS_DeleteUnsetRows()

epicsShareFuncSDDS int32_t SDDS_DeleteUnsetRows ( SDDS_DATASET * SDDS_dataset )

extern

Deletes rows from an SDDS dataset that are not marked as "of interest".

This function removes all rows in the provided SDDS dataset that have not been flagged as "of interest" using prior selection functions. It effectively compacts the dataset by retaining only the desired rows and updating the row count accordingly.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

On success, returns 1. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that rows were successfully deleted.
0	Indicates that an error occurred (e.g., invalid dataset, problem copying rows).

Note

• This operation modifies the dataset in place by removing unset rows.
• It is recommended to perform row selection before calling this function to ensure that only desired rows are retained.

See also

SDDS_SetRowsOfInterest, SDDS_MatchRowsOfInterest, SDDS_FilterRowsOfInterest

Definition at line 3761 of file SDDS_extract.c.

                                                         {
  int64_t i, j;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DeleteUnsetRows"))
    return (0);
 
  for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
    if (SDDS_dataset->row_flag[i]) {
      if (i != j) {
        SDDS_dataset->row_flag[j] = SDDS_dataset->row_flag[i];
        if (!SDDS_TransferRow(SDDS_dataset, j, i)) {
          SDDS_SetError("Unable to delete unset rows--problem copying row (SDDS_DeleteUnsetRows)");
          return (0);
        }
      }
      j++;
    }
  }
  SDDS_dataset->n_rows = j;
  return (1);
}

SDDS_DisableFSync()

epicsShareFuncSDDS void SDDS_DisableFSync ( SDDS_DATASET * SDDS_dataset )

extern

Disables file synchronization for the SDDS dataset.

This function disables the file synchronization feature for the specified SDDS dataset. File synchronization ensures that all buffered data is immediately written to disk, enhancing data integrity. By disabling this feature, the dataset will no longer perform synchronous writes, which can improve performance but may risk data loss in the event of a system failure.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Postcondition

• File synchronization is disabled, meaning that SDDS_SyncDataSet will not call fsync.

Note

• Disabling file synchronization can lead to improved performance, especially when writing large datasets.
• It is recommended to use this function only when performance is a higher priority than immediate data integrity.

Warning

• Without file synchronization, there is a risk of data loss if the system crashes before buffered data is written to disk.
• Ensure that data integrity is managed through other means if synchronization is disabled.

Definition at line 2394 of file SDDS_output.c.

                                                   {
  SDDS_dataset->layout.data_mode.fsync_data = 0;
}

SDDS_DisconnectFile()

epicsShareFuncSDDS int32_t SDDS_DisconnectFile ( SDDS_DATASET * SDDS_dataset )

extern

Disconnects the SDDS dataset from its associated file.

This function terminates the connection between the SDDS dataset and the file it is currently linked to. It ensures that all pending data is flushed to the file, closes the file handle, and updates the dataset's internal state to reflect that it is no longer connected to any file.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure to be disconnected.

Returns

• 1 on successful disconnection.
• 0 if an error occurred during disconnection. In this case, an error message is set internally.

Note

• If the dataset is already disconnected, this function will return an error.
• This function is not thread-safe if the dataset is being accessed concurrently.

Warning

• Ensure that no further operations are performed on the dataset after disconnection unless it is reconnected.

Definition at line 71 of file SDDS_output.c.

                                                        {
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io)
    return SDDS_MPI_DisconnectFile(SDDS_dataset);
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DisconnectFile"))
    return 0;
  if (!SDDS_dataset->layout.filename) {
    SDDS_SetError("Can't disconnect file. No filename given. (SDDS_DisconnectFile)");
    return 0;
  }
  if (SDDS_dataset->layout.gzipFile) {
    SDDS_SetError("Can't disconnect file because it is a gzip file. (SDDS_DisconnectFile)");
    return 0;
  }
  if (SDDS_dataset->layout.lzmaFile) {
    SDDS_SetError("Can't disconnect file because it is a lzma or xz file. (SDDS_DisconnectFile)");
    return 0;
  }
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't disconnect file.  Already disconnected. (SDDS_DisconnectFile)");
    return 0;
  }
  if (SDDS_dataset->page_started && !SDDS_UpdatePage(SDDS_dataset, FLUSH_TABLE)) {
    SDDS_SetError("Can't disconnect file.  Problem updating page. (SDDS_DisconnectFile)");
    return 0;
  }
  if (fclose(SDDS_dataset->layout.fp)) {
    SDDS_SetError("Can't disconnect file.  Problem closing file. (SDDS_DisconnectFile)");
    return 0;
  }
  SDDS_dataset->layout.disconnected = 1;
  return 1;
}

SDDS_DisconnectInputFile()

epicsShareFuncSDDS long SDDS_DisconnectInputFile ( SDDS_DATASET * SDDS_dataset )

extern

Disconnects the input file from the SDDS dataset.

This function severs the connection between the SDDS dataset and its input file. It closes the file handle, updates the dataset's internal state to indicate disconnection, and returns the current file position before closing. After disconnection, the dataset cannot read further data from the input file until it is reconnected.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure whose input file is to be disconnected.

Returns

• On success, returns the current file position (as obtained by ftell) before disconnection.
• On failure, returns -1 and sets an internal error message.

Note

• This function cannot disconnect compressed input files (gzip, lzma, xz).
• Attempting to disconnect an already disconnected dataset will result in an error.

Warning

• Ensure that no further read operations are performed on the dataset after disconnection unless it is reconnected.

Definition at line 171 of file SDDS_output.c.

                                                          {
  long position;
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io) {
    SDDS_SetError("Error: MPI mode not supported yet in SDDS_DisconnectInputFile");
    return -1;
  }
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_DisconnectInputFile"))
    return -1;
  if (!SDDS_dataset->layout.filename) {
    SDDS_SetError("Can't disconnect file. No filename given. (SDDS_DisconnectInputFile)");
    return -1;
  }
  if (SDDS_dataset->layout.gzipFile) {
    SDDS_SetError("Can't disconnect file because it is a gzip file. (SDDS_DisconnectInputFile)");
    return -1;
  }
  if (SDDS_dataset->layout.lzmaFile) {
    SDDS_SetError("Can't disconnect file because it is a lzma or xz file. (SDDS_DisconnectInputFile)");
    return -1;
  }
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't disconnect file.  Already disconnected. (SDDS_DisconnectInputFile)");
    return -1;
  }
  position = ftell(SDDS_dataset->layout.fp);
  if (fclose(SDDS_dataset->layout.fp)) {
    SDDS_SetError("Can't disconnect file.  Problem closing file. (SDDS_DisconnectInputFile)");
    return -1;
  }
  SDDS_dataset->layout.disconnected = 1;
  return position;
}

SDDS_DoFSync()

epicsShareFuncSDDS int32_t SDDS_DoFSync ( SDDS_DATASET * SDDS_dataset )

extern

Synchronizes the SDDS dataset's file to disk.

Performs a file synchronization operation on the specified SDDS dataset to ensure that all buffered data is flushed to the storage medium. This is crucial for maintaining data integrity, especially in scenarios where unexpected shutdowns or crashes may occur.

Platform-Specific Behavior

• vxWorks, Windows (_WIN32), macOS (APPLE):
  • The function assumes that synchronization is always successful and returns 1.
• Other Platforms:
  • Attempts to flush the dataset's file buffer to disk using the fsync system call.
  • Returns 1 if fsync succeeds, indicating successful synchronization.
  • Returns 0 if fsync fails or if the dataset/file pointer is invalid.

Parameters

[in]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to be synchronized.

Returns

int32_t

• 1 on successful synchronization.
• 0 on failure.

Definition at line 2443 of file SDDS_output.c.

                                                 {
#if defined(vxWorks) || defined(_WIN32) || defined(__APPLE__)
  return 1;
#else
  if (SDDS_dataset && SDDS_dataset->layout.fp)
    return fsync(fileno(SDDS_dataset->layout.fp)) == 0;
  return 0;
#endif
}

SDDS_EnableFSync()

epicsShareFuncSDDS void SDDS_EnableFSync ( SDDS_DATASET * SDDS_dataset )

extern

Enables file synchronization for the SDDS dataset.

This function enables the file synchronization feature for the specified SDDS dataset. File synchronization ensures that all buffered data is immediately written to disk, enhancing data integrity. Enabling this feature can be crucial for applications where data consistency and reliability are paramount.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Postcondition

• File synchronization is enabled, meaning that SDDS_SyncDataSet will call fsync to flush buffers to disk.

Note

• Enabling file synchronization may impact performance due to the increased number of disk write operations.
• It is recommended to enable synchronization when data integrity is critical, such as in transactional systems.

Warning

• Frequent synchronization can lead to reduced performance, especially when writing large amounts of data.
• Balance the need for data integrity with performance requirements based on the specific use case.

Definition at line 2418 of file SDDS_output.c.

                                                  {
  SDDS_dataset->layout.data_mode.fsync_data = 1;
}

SDDS_EraseData()

epicsShareFuncSDDS int32_t SDDS_EraseData ( SDDS_DATASET * SDDS_dataset )

extern

Erases all data entries in the SDDS dataset.

This function removes all data from the specified SDDS dataset, effectively resetting it to an empty state. It frees any allocated memory associated with data columns, parameters, and arrays, ensuring that all dynamic data is properly cleared. This is useful for reusing the dataset for new data without retaining previous entries.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• 1 on successful erasure of all data.
• 0 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured.

Postcondition

• All data rows are removed from the dataset.
• Memory allocated for data columns, parameters, and arrays is freed.
• The dataset is ready to accept new data entries.

Note

• This function does not alter the dataset's layout definitions; only the data entries are cleared.
• After erasing data, the dataset can be reused to write new data tables without redefining the layout.

Warning

• Erasing data is irreversible; ensure that any necessary data is backed up before calling this function.
• Concurrent access to the dataset while erasing data may lead to undefined behavior.

Definition at line 2264 of file SDDS_output.c.

                                                   {
  SDDS_LAYOUT *layout;
  int64_t i, j;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_EraseData"))
    return 0;
  layout = &SDDS_dataset->layout;
  if (SDDS_dataset->data) {
    for (i = 0; i < layout->n_columns; i++) {
      if (!SDDS_dataset->data[i])
        continue;
      if (layout->column_definition[i].type == SDDS_STRING) {
        for (j = 0; j < SDDS_dataset->n_rows; j++) {
          if (((char **)SDDS_dataset->data[i])[j]) {
            free(((char **)SDDS_dataset->data[i])[j]);
            ((char **)SDDS_dataset->data[i])[j] = NULL;
          }
        }
      }
    }
  }
  SDDS_dataset->n_rows = 0;
 
  if (SDDS_dataset->parameter) {
    for (i = 0; i < layout->n_parameters; i++) {
      if (!SDDS_dataset->parameter[i])
        continue;
      if (layout->parameter_definition[i].type == SDDS_STRING && *(char **)(SDDS_dataset->parameter[i])) {
        free(*(char **)(SDDS_dataset->parameter[i]));
        *(char **)SDDS_dataset->parameter[i] = NULL;
      }
    }
  }
 
  if (SDDS_dataset->array) {
    for (i = 0; i < layout->n_arrays; i++) {
      if (SDDS_dataset->array[i].definition->type == SDDS_STRING) {
        for (j = 0; j < SDDS_dataset->array[i].elements; j++) {
          if (((char **)SDDS_dataset->array[i].data)[j]) {
            free(((char **)SDDS_dataset->array[i].data)[j]);
            ((char **)SDDS_dataset->array[i].data)[j] = NULL;
          }
        }
      }
    }
  }
 
  return (1);
}

SDDS_EscapeCommentCharacters()

epicsShareFuncSDDS void SDDS_EscapeCommentCharacters ( char * string, char cc )

extern

Escapes comment characters within a string by inserting backslashes.

This function scans the input string string and inserts a backslash (\) before each occurrence of the specified comment character cc, provided it is not already escaped. This is useful for preparing strings to include comment characters without them being interpreted as actual comments.

Parameters

[in,out]	string	Pointer to the string in which comment characters will be escaped. The string will be modified in place.
[in]	cc	The comment character to escape (e.g., #).

Note

The function dynamically allocates a temporary buffer to perform the escaping process and ensures that the original string string is updated correctly. The caller must ensure that string has sufficient space to accommodate the additional backslashes.

See also

SDDS_CutOutComments

Definition at line 2021 of file SDDS_utils.c.

                                                         {
  char *ptr, *s0;
  s0 = string;
  while (*string) {
    if (*string == cc && (string == s0 || *(string - 1) != '\\')) {
      ptr = string + strlen(string) + 1;
      while (ptr != string) {
        *ptr = *(ptr - 1);
        ptr--;
      }
      *string++ = '\\';
    }
    string++;
  }
}

SDDS_EscapeNewlines()

epicsShareFuncSDDS void SDDS_EscapeNewlines ( char * s )

extern

Escapes newline characters in a string by replacing them with "\\n".

This function modifies the input string s in place by replacing each newline character (‘’
') with the two-character sequence'\'and'n'`. It shifts the subsequent characters in the string to accommodate the additional character introduced by the escape sequence.

Parameters

[in,out]

s

Pointer to the null-terminated string to be modified. Important: The buffer pointed to by s must have sufficient space to accommodate the additional characters resulting from the escape sequences. Failure to ensure adequate space may lead to buffer overflows.

Warning

This function does not perform bounds checking on the buffer size. Ensure that the buffer is large enough to handle the increased length after escaping newlines.

See also

SDDS_UnescapeNewlines

Definition at line 3264 of file SDDS_utils.c.

                                  {
  char *ptr;
  while (*s) {
    if (*s == '\n') {
      ptr = s + strlen(s);
      *(ptr + 1) = 0;
      while (ptr != s) {
        *ptr = *(ptr - 1);
        ptr--;
      }
      *s++ = '\\';
      *s++ = 'n';
    } else
      s++;
  }
}

SDDS_EscapeQuotes()

epicsShareFuncSDDS void SDDS_EscapeQuotes ( char * s, char quote_char )

extern

Escapes quote characters within a string by inserting backslashes.

This function scans the input string s and inserts a backslash (\) before each occurrence of the specified quote_char, provided it is not already escaped. This is useful for preparing strings for formats that require escaped quotes.

Parameters

[in,out]	s	Pointer to the string in which quotes will be escaped. The string will be modified in place.
[in]	quote_char	The quote character to escape (e.g., ").

Note

The function dynamically allocates a temporary buffer to perform the escaping process and ensures that the original string s is updated correctly. The caller must ensure that s has sufficient space to accommodate the additional backslashes.

See also

SDDS_UnescapeQuotes

Definition at line 1967 of file SDDS_utils.c.

                                                 {
  char *ptr, *bptr;
  char *buffer = NULL;
 
  ptr = s;
  buffer = trealloc(buffer, sizeof(*buffer) * (4 * (strlen(s) + 1)));
  bptr = buffer;
 
  while (*ptr) {
    if (*ptr == quote_char && (ptr == s || *(ptr - 1) != '\\'))
      *bptr++ = '\\';
    *bptr++ = *ptr++;
  }
  *bptr = 0;
  strcpy(s, buffer);
  if (buffer)
    free(buffer);
}

SDDS_FileIsLocked()

epicsShareFuncSDDS int32_t SDDS_FileIsLocked ( const char * filename )

extern

Determines if a specified file is locked.

This function checks whether the given file is currently locked. If file locking is enabled through the F_TEST and ALLOW_FILE_LOCKING macros, it attempts to open the file and apply a test lock using lockf. The function returns 1 if the file is locked and 0 otherwise.

If file locking is not enabled (i.e., the F_TEST and ALLOW_FILE_LOCKING macros are not defined), the function always returns 0, indicating that the file is not locked.

Parameters

[in]

filename

The path to the file to be checked for a lock.

Returns

• 1 if the file is locked.
• 0 if the file is not locked or if file locking is not enabled.

Note

The effectiveness of this function depends on the platform and the implementation of file locking mechanisms.

Warning

Ensure that the F_TEST and ALLOW_FILE_LOCKING macros are appropriately defined to enable file locking functionality.

See also

SDDS_LockFile

Definition at line 3357 of file SDDS_utils.c.

                                                {
#if defined(F_TEST) && ALLOW_FILE_LOCKING
  FILE *fp;
  if (!(fp = fopen(filename, "rb")))
    return 0;
  if (lockf(fileno(fp), F_TEST, 0) == -1) {
    fclose(fp);
    return 1;
  }
  fclose(fp);
  return 0;
#else
  return 0;
#endif
}

SDDS_FilterRowsByNumScan()

epicsShareFuncSDDS int64_t SDDS_FilterRowsByNumScan ( SDDS_DATASET * SDDS_dataset, char * filter_column, uint32_t mode )

extern

Filters rows of interest in an SDDS dataset based on numeric scanning of a specified column.

This function marks rows in the provided SDDS dataset as "of interest" based on whether the entries in the specified filter column can be interpreted as valid numbers. It supports inversion of the filtering criterion through the mode parameter.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
filter_column	A null-terminated string specifying the name of the column used for numeric scanning. This column must not be of string type.
mode	An unsigned integer representing mode flags. Supported flags include: NUMSCANFILTER_INVERT: Invert the filtering criterion (select rows where the entry is not a number).

Returns

On success, returns the number of rows marked as "of interest" after filtering. On failure, returns -1 and sets an appropriate error message.

Return values

-1	Indicates that an error occurred (e.g., invalid dataset, unrecognized filter column, filter column is of string type).
Non-negative	Integer representing the count of rows marked as "of interest".

Note

• The filter column must exist and must not be of string type.
• The function uses tokenIsNumber to determine if an entry is a valid number.

See also

SDDS_SetRowsOfInterest, SDDS_MatchRowsOfInterest, SDDS_DeleteUnsetRows

Definition at line 3698 of file SDDS_extract.c.

                                                                                                 {
  int32_t accept, index;
  int64_t i, count;
  short invert;
  char *ptr;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_FilterRowsByNumScan"))
    return (-1);
  if (!filter_column) {
    SDDS_SetError("Unable to filter rows--filter column name not given (SDDS_FilterRowsByNumScan)");
    return (-1);
  }
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, filter_column)) < 0) {
    SDDS_SetError("Unable to filter rows--column name is unrecognized (SDDS_FilterRowsByNumScan)");
    return (-1);
  }
  switch (SDDS_GetColumnType(SDDS_dataset, index)) {
  case SDDS_SHORT:
  case SDDS_USHORT:
  case SDDS_LONG:
  case SDDS_ULONG:
  case SDDS_LONG64:
  case SDDS_ULONG64:
  case SDDS_FLOAT:
  case SDDS_DOUBLE:
  case SDDS_LONGDOUBLE:
  case SDDS_CHARACTER:
    SDDS_SetError("Unable to filter rows--filter column is not string type (SDDS_FilterRowsByNumScan)");
    return (-1);
  default:
    break;
  }
  invert = mode & NUMSCANFILTER_INVERT ? 1 : 0;
  for (i = count = 0; i < SDDS_dataset->n_rows; i++) {
    ptr = ((char **)(SDDS_dataset->data[index]))[i];
    accept = !invert;
    if (!tokenIsNumber(ptr))
      accept = invert;
    if ((SDDS_dataset->row_flag[i] = accept))
      count++;
  }
  return (count);
}

SDDS_FilterRowsOfInterest()

epicsShareFuncSDDS int64_t SDDS_FilterRowsOfInterest ( SDDS_DATASET * SDDS_dataset, char * filter_column, double lower_limit, double upper_limit, int32_t logic )

extern

Filters rows of interest in an SDDS dataset based on numeric ranges in a specified column.

This function marks rows in the provided SDDS dataset as "of interest" if the values in the specified filter column fall within the defined numeric range (lower_limit to upper_limit). Logical operations specified by the logic parameter determine how the filtering interacts with existing row flags.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
filter_column	A null-terminated string specifying the name of the column used for numeric filtering. This column must be of a numeric type.
lower_limit	The lower bound of the numeric range. Rows with values below this limit are excluded.
upper_limit	The upper bound of the numeric range. Rows with values above this limit are excluded.
logic	An integer representing logical operation flags. Supported flags include: SDDS_NEGATE_PREVIOUS: Invert the previous row flag. SDDS_NEGATE_MATCH: Invert the match result. SDDS_AND: Combine with existing row flags using logical AND. SDDS_OR: Combine with existing row flags using logical OR. SDDS_NEGATE_EXPRESSION: Invert the entire logical expression.

Returns

On success, returns the number of rows marked as "of interest" after filtering. On failure, returns -1 and sets an appropriate error message.

Return values

-1	Indicates that an error occurred (e.g., invalid dataset, unrecognized filter column, non-numeric filter column).
Non-negative	Integer representing the count of rows marked as "of interest".

Note

• The filter column must exist and be of a numeric type (e.g., SDDS_SHORT, SDDS_USHORT, SDDS_LONG, SDDS_ULONG, SDDS_LONG64, SDDS_ULONG64, SDDS_FLOAT, SDDS_DOUBLE, SDDS_LONGDOUBLE).
• Logical flags determine how the filtering interacts with existing row flags. Multiple flags can be combined using bitwise OR.

See also

SDDS_SetRowsOfInterest, SDDS_MatchRowsOfInterest, SDDS_DeleteUnsetRows

Definition at line 3629 of file SDDS_extract.c.

                                                                                                                                          {
  int32_t accept, type, index;
  int64_t i, count;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_FilterRowsOfInterest"))
    return (-1);
  if (!filter_column) {
    SDDS_SetError("Unable to filter rows--filter column name not given (SDDS_FilterRowsOfInterest)");
    return (-1);
  }
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, filter_column)) < 0) {
    SDDS_SetError("Unable to filter rows--column name is unrecognized (SDDS_FilterRowsOfInterest)");
    return (-1);
  }
  switch (type = SDDS_GetColumnType(SDDS_dataset, index)) {
  case SDDS_SHORT:
  case SDDS_USHORT:
  case SDDS_LONG:
  case SDDS_ULONG:
  case SDDS_LONG64:
  case SDDS_ULONG64:
  case SDDS_FLOAT:
  case SDDS_DOUBLE:
  case SDDS_LONGDOUBLE:
    break;
  default:
    SDDS_SetError("Unable to filter rows--filter column is not a numeric type (SDDS_FilterRowsOfInterest)");
    return (-1);
  }
  for (i = count = 0; i < SDDS_dataset->n_rows; i++) {
    if (logic & SDDS_NEGATE_PREVIOUS)
      SDDS_dataset->row_flag[i] = !SDDS_dataset->row_flag[i];
    accept = SDDS_ItemInsideWindow(SDDS_dataset->data[index], i, type, lower_limit, upper_limit);
    if (logic & SDDS_NEGATE_MATCH)
      accept = !accept;
    if (logic & SDDS_AND)
      accept = accept && SDDS_dataset->row_flag[i];
    else if (logic & SDDS_OR)
      accept = accept || SDDS_dataset->row_flag[i];
    if (logic & SDDS_NEGATE_EXPRESSION)
      accept = !accept;
    if ((SDDS_dataset->row_flag[i] = accept))
      count++;
  }
  return (count);
}

SDDS_FindArray()

epicsShareFuncSDDS char * SDDS_FindArray ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Finds the first array in the SDDS dataset that matches the specified criteria.

This function searches through the arrays of the provided SDDS dataset and returns the name of the first array that matches the given criteria based on the specified mode.

The function supports the following modes:

• FIND_SPECIFIED_TYPE:
  • Parameters: int32_t type, char *name1, char *name2, ..., NULL
  • Description: Finds the first array with a specified type among the provided array names.
• FIND_ANY_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first array with any type among the provided array names.
• FIND_NUMERIC_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first array with a numeric type among the provided array names.
• FIND_FLOATING_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first array with a floating type among the provided array names.
• FIND_INTEGER_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first array with an integer type among the provided array names.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure containing the dataset.
[in]	mode	Specifies the mode for matching arrays. Valid modes are: FIND_SPECIFIED_TYPE FIND_ANY_TYPE FIND_NUMERIC_TYPE FIND_FLOATING_TYPE FIND_INTEGER_TYPE
[in]	...	Variable arguments depending on mode: FIND_SPECIFIED_TYPE: int32_t type, followed by a list of array names (char *name1, char *name2, ..., NULL) Other Modes: A list of array names (char *name1, char *name2, ..., NULL)

Returns

• On success, returns a dynamically allocated string containing the name of the first matched array.
• Returns NULL if no matching array is found or if an error occurs (e.g., memory allocation failure).

Note

• The caller is responsible for freeing the memory allocated for the returned string using free() or an appropriate memory deallocation function.
• Ensure that the SDDS dataset is properly initialized and contains arrays before calling this function.

Warning

• Ensure that the variable arguments match the expected parameters for the specified mode.
• Failure to free the returned string may lead to memory leaks.

See also

SDDS_FindColumn, SDDS_FindParameter, SDDS_MatchArrays, SDDS_SetError

Definition at line 4575 of file SDDS_utils.c.

                                                                    {
  int32_t index, error, type, thisType;
  va_list argptr;
  char *name, *buffer;
 
  va_start(argptr, mode);
  buffer = NULL;
  error = type = 0;
 
  if (mode == FIND_SPECIFIED_TYPE)
    type = va_arg(argptr, int32_t);
  while ((name = va_arg(argptr, char *))) {
    if ((index = SDDS_GetArrayIndex(SDDS_dataset, name)) >= 0) {
      thisType = SDDS_GetArrayType(SDDS_dataset, index);
      if (mode == FIND_ANY_TYPE || (mode == FIND_SPECIFIED_TYPE && thisType == type) || (mode == FIND_NUMERIC_TYPE && SDDS_NUMERIC_TYPE(thisType)) || (mode == FIND_FLOATING_TYPE && SDDS_FLOATING_TYPE(thisType)) || (mode == FIND_INTEGER_TYPE && SDDS_INTEGER_TYPE(thisType))) {
        if (!SDDS_CopyString(&buffer, name)) {
          SDDS_SetError("unable to return string from SDDS_FindArray");
          error = 1;
          break;
        }
        error = 0;
        break;
      }
    }
  }
  va_end(argptr);
  if (error)
    return NULL;
  return buffer;
}

SDDS_FindColumn()

epicsShareFuncSDDS char * SDDS_FindColumn ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Finds the first column in the SDDS dataset that matches the specified criteria.

This function searches through the columns of the provided SDDS dataset and returns the name of the first column that matches the given criteria based on the specified mode.

The function supports the following modes:

• FIND_SPECIFIED_TYPE:
  • Parameters: int32_t type, char *name1, char *name2, ..., NULL
  • Description: Finds the first column with a specified type among the provided column names.
• FIND_ANY_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first column with any type among the provided column names.
• FIND_NUMERIC_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first column with a numeric type among the provided column names.
• FIND_FLOATING_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first column with a floating type among the provided column names.
• FIND_INTEGER_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first column with an integer type among the provided column names.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure containing the dataset.
[in]	mode	Specifies the mode for matching columns. Valid modes are: FIND_SPECIFIED_TYPE FIND_ANY_TYPE FIND_NUMERIC_TYPE FIND_FLOATING_TYPE FIND_INTEGER_TYPE
[in]	...	Variable arguments depending on mode: FIND_SPECIFIED_TYPE: int32_t type, followed by a list of column names (char *name1, char *name2, ..., NULL) Other Modes: A list of column names (char *name1, char *name2, ..., NULL)

Returns

• On success, returns a dynamically allocated string containing the name of the first matched column.
• Returns NULL if no matching column is found or if an error occurs (e.g., memory allocation failure).

Note

• The caller is responsible for freeing the memory allocated for the returned string using free() or an appropriate memory deallocation function.
• Ensure that the SDDS dataset is properly initialized and contains columns before calling this function.

Warning

• Ensure that the variable arguments match the expected parameters for the specified mode.
• Failure to free the returned string may lead to memory leaks.

See also

SDDS_FindParameter, SDDS_FindArray, SDDS_MatchColumns, SDDS_SetError

Definition at line 4396 of file SDDS_utils.c.

                                                                     {
  /*
    SDDS_DATASET *SDDS_dataset, FIND_SPECIFIED_TYPE, int32_t type, char*, ..., NULL)
    SDDS_DATASET *SDDS_dataset, FIND_ANY_TYPE, char*, ..., NULL)
  */
  int32_t index;
  int32_t error, type, thisType;
  va_list argptr;
  char *name, *buffer;
 
  va_start(argptr, mode);
  buffer = NULL;
  error = type = 0;
 
  if (mode == FIND_SPECIFIED_TYPE)
    type = va_arg(argptr, int32_t);
  while ((name = va_arg(argptr, char *))) {
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) >= 0) {
      thisType = SDDS_GetColumnType(SDDS_dataset, index);
      if (mode == FIND_ANY_TYPE || (mode == FIND_SPECIFIED_TYPE && thisType == type) || (mode == FIND_NUMERIC_TYPE && SDDS_NUMERIC_TYPE(thisType)) || (mode == FIND_FLOATING_TYPE && SDDS_FLOATING_TYPE(thisType)) || (mode == FIND_INTEGER_TYPE && SDDS_INTEGER_TYPE(thisType))) {
        if (!SDDS_CopyString(&buffer, name)) {
          SDDS_SetError("unable to return string from SDDS_FindColumn");
          error = 1;
          break;
        }
        error = 0;
        break;
      }
    }
  }
  va_end(argptr);
  if (error)
    return NULL;
  return buffer;
}

SDDS_FindParameter()

epicsShareFuncSDDS char * SDDS_FindParameter ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Finds the first parameter in the SDDS dataset that matches the specified criteria.

This function searches through the parameters of the provided SDDS dataset and returns the name of the first parameter that matches the given criteria based on the specified mode.

The function supports the following modes:

• FIND_SPECIFIED_TYPE:
  • Parameters: int32_t type, char *name1, char *name2, ..., NULL
  • Description: Finds the first parameter with a specified type among the provided parameter names.
• FIND_ANY_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first parameter with any type among the provided parameter names.
• FIND_NUMERIC_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first parameter with a numeric type among the provided parameter names.
• FIND_FLOATING_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first parameter with a floating type among the provided parameter names.
• FIND_INTEGER_TYPE:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Finds the first parameter with an integer type among the provided parameter names.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure containing the dataset.
[in]	mode	Specifies the mode for matching parameters. Valid modes are: FIND_SPECIFIED_TYPE FIND_ANY_TYPE FIND_NUMERIC_TYPE FIND_FLOATING_TYPE FIND_INTEGER_TYPE
[in]	...	Variable arguments depending on mode: FIND_SPECIFIED_TYPE: int32_t type, followed by a list of parameter names (char *name1, char *name2, ..., NULL) Other Modes: A list of parameter names (char *name1, char *name2, ..., NULL)

Returns

• On success, returns a dynamically allocated string containing the name of the first matched parameter.
• Returns NULL if no matching parameter is found or if an error occurs (e.g., memory allocation failure).

Note

• The caller is responsible for freeing the memory allocated for the returned string using free() or an appropriate memory deallocation function.
• Ensure that the SDDS dataset is properly initialized and contains parameters before calling this function.

Warning

• Ensure that the variable arguments match the expected parameters for the specified mode.
• Failure to free the returned string may lead to memory leaks.

See also

SDDS_FindColumn, SDDS_FindArray, SDDS_MatchParameters, SDDS_SetError

Definition at line 4488 of file SDDS_utils.c.

                                                                        {
  int32_t index, error, type, thisType;
  va_list argptr;
  char *name, *buffer;
 
  va_start(argptr, mode);
  buffer = NULL;
  error = type = 0;
 
  if (mode == FIND_SPECIFIED_TYPE)
    type = va_arg(argptr, int32_t);
  while ((name = va_arg(argptr, char *))) {
    if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) >= 0) {
      thisType = SDDS_GetParameterType(SDDS_dataset, index);
      if (mode == FIND_ANY_TYPE || (mode == FIND_SPECIFIED_TYPE && thisType == type) || (mode == FIND_NUMERIC_TYPE && SDDS_NUMERIC_TYPE(thisType)) || (mode == FIND_FLOATING_TYPE && SDDS_FLOATING_TYPE(thisType)) || (mode == FIND_INTEGER_TYPE && SDDS_INTEGER_TYPE(thisType))) {
        if (!SDDS_CopyString(&buffer, name)) {
          SDDS_SetError("unable to return string from SDDS_FindParameter");
          error = 1;
          break;
        }
        error = 0;
        break;
      }
    }
  }
  va_end(argptr);
  if (error)
    return NULL;
  return buffer;
}

SDDS_FlushBuffer()

epicsShareFuncSDDS int32_t SDDS_FlushBuffer ( FILE * fp, SDDS_FILEBUFFER * fBuffer )

extern

Flushes the buffered data to a file to ensure all data is written.

This function writes any remaining data in the buffer (fBuffer) to the file pointed to by fp. If the buffer contains data, it writes the data to the file, resets the buffer, and flushes the file's output buffer using fflush. This ensures that all buffered data is physically written to the file.

Parameters

fp	The file pointer to which buffered data will be written.
fBuffer	Pointer to an SDDS_FILEBUFFER structure containing the buffered data.

Returns

Returns 1 on success; returns 0 on error.

Note

If fBuffer->bufferSize is zero, the function will only call fflush(fp).

Warning

If fp or fBuffer is NULL, the function sets an error message and returns 0.

Definition at line 650 of file SDDS_binary.c.

                                                             {
  int64_t writeBytes;
  if (!fp) {
    SDDS_SetError("Unable to flush buffer: file pointer is NULL. (SDDS_FlushBuffer)");
    return 0;
  }
  if (!fBuffer) {
    SDDS_SetError("Unable to flush buffer: buffer pointer is NULL. (SDDS_FlushBuffer)");
    return 0;
  }
  if (!fBuffer->bufferSize) {
    if (fflush(fp)) {
      SDDS_SetError("Problem flushing file (SDDS_FlushBuffer.1)");
      SDDS_SetError(strerror(errno));
      return 0;
    }
    return 1;
  }
  if ((writeBytes = fBuffer->bufferSize - fBuffer->bytesLeft)) {
    if (writeBytes < 0) {
      SDDS_SetError("Unable to flush buffer: negative byte count (SDDS_FlushBuffer).");
      return 0;
    }
#ifdef DEBUG
    fprintf(stderr, "Writing %" PRId64 " bytes to disk\n", writeBytes);
#endif
    if (fwrite(fBuffer->buffer, 1, writeBytes, fp) != writeBytes) {
      SDDS_SetError("Unable to flush buffer: write operation failed (SDDS_FlushBuffer).");
      return 0;
    }
    fBuffer->bytesLeft = fBuffer->bufferSize;
    fBuffer->data = fBuffer->buffer;
  }
  if (fflush(fp)) {
    SDDS_SetError("Problem flushing file (SDDS_FlushBuffer.2)");
    SDDS_SetError(strerror(errno));
    return 0;
  }
  return 1;
}

SDDS_ForceInactive()

epicsShareFuncSDDS int32_t SDDS_ForceInactive ( SDDS_DATASET * SDDS_dataset )

extern

Marks an SDDS dataset as inactive.

This function forces the provided SDDS dataset to become inactive by setting its file pointer to NULL. An inactive dataset is typically not associated with any open file operations.

Parameters

[in]

SDDS_dataset

Pointer to the SDDS_DATASET structure to be marked as inactive.

Returns

• 1 on successful operation.
• -1 if a NULL pointer is passed, indicating an error.

Note

After calling this function, the dataset will be considered inactive, and any subsequent operations that require an active dataset may fail.

See also

SDDS_IsActive, SDDS_SetError

Definition at line 3298 of file SDDS_utils.c.

                                                       {
  if (!SDDS_dataset) {
    SDDS_SetError("NULL SDDS_DATASET passed (SDDS_ForceInactive)");
    return (-1);
  }
  SDDS_dataset->layout.fp = NULL;
  return (1);
}

SDDS_Free()

epicsShareFuncSDDS void SDDS_Free ( void * mem )

extern

Free memory previously allocated by SDDS_Malloc.

This function frees memory that wsa previously allocated by SDDS_Malloc.

Parameters

[in]

mem

Pointer to the memory block.

See also

SDDS_Malloc

SDDS_Calloc

Definition at line 721 of file SDDS_utils.c.

                          {
  /* this is required so the free will be consistent with the malloc.
     On WIN32 the release (optimized) version of malloc is different
     from the debug (unoptimized) version, so debug programs freeing
     memory that was allocated by release, library routines encounter
     problems. */
  free(mem);
}

SDDS_FreeArray()

epicsShareFuncSDDS void SDDS_FreeArray ( SDDS_ARRAY * array )

extern

Frees memory allocated for an SDDS array structure.

This function deallocates all memory associated with an SDDS_ARRAY structure, including its data and definition. It handles the freeing of string elements if the array type is SDDS_STRING and ensures that all pointers are set to NULL after deallocation to prevent dangling references.

Parameters

[in]

array

Pointer to the SDDS_ARRAY structure to be freed.

Note

• The function assumes that the array's data and definitions were allocated using SDDS memory management functions.
• After calling this function, the array pointer becomes invalid and should not be used.

See also

SDDS_FreePointerArray

SDDS_FreeArrayDefinition

SDDS_Free

Definition at line 2832 of file SDDS_utils.c.

                                       {
  int i;
  if (!array)
    return;
  if (array->definition) {
    if ((array->definition->type == SDDS_STRING) && (array->data)) {
      char **str = (char **)array->data;
      for (i = 0; i < array->elements; i++) {
        if (str[i])
          free(str[i]);
        str[i] = NULL;
      }
    }
  }
  if (array->definition && array->pointer)
    SDDS_FreePointerArray(array->pointer, array->definition->dimensions, array->dimension);
  if (array->data)
    free(array->data);
  array->pointer = array->data = NULL;
  if (array->dimension)
    free(array->dimension);
  if (array->definition)
    SDDS_FreeArrayDefinition(array->definition);
  array->definition = NULL;
  free(array);
  array = NULL;
}

SDDS_FreeArrayDefinition()

epicsShareFuncSDDS int32_t SDDS_FreeArrayDefinition ( ARRAY_DEFINITION * source )

extern

Frees memory allocated for an array definition.

This function deallocates all memory associated with an ARRAY_DEFINITION structure, including its string fields. After freeing, the structure is zeroed out to prevent dangling pointers.

Parameters

[in]

source

Pointer to the ARRAY_DEFINITION structure to be freed.

Returns

Returns 1 on successful deallocation. Returns 0 if the source is NULL.

Note

After calling this function, the source pointer becomes invalid and should not be used.

See also

SDDS_CopyArrayDefinition

SDDS_Free

Definition at line 1304 of file SDDS_utils.c.

                                                           {
  if (!source)
    return (0);
  if (source->name)
    free(source->name);
  if (source->symbol)
    free(source->symbol);
  if (source->units)
    free(source->units);
  if (source->description)
    free(source->description);
  if (source->format_string)
    free(source->format_string);
  if (source->group_name)
    free(source->group_name);
  SDDS_ZeroMemory(source, sizeof(*source));
  free(source);
  source = NULL;
  return (1);
}

SDDS_FreeAssociateDefinition()

epicsShareFuncSDDS int32_t SDDS_FreeAssociateDefinition ( ASSOCIATE_DEFINITION * source )

extern

Frees memory allocated for an associate definition.

This function deallocates all memory associated with an ASSOCIATE_DEFINITION structure, including its string fields. After freeing, the structure is zeroed out to prevent dangling pointers.

Parameters

[in]

source

Pointer to the ASSOCIATE_DEFINITION structure to be freed.

Returns

Returns 1 on successful deallocation. Returns 0 if the source is NULL or if required fields are missing.

Note

After calling this function, the source pointer becomes invalid and should not be used.

See also

SDDS_CopyAssociateDefinition

SDDS_Free

Definition at line 1010 of file SDDS_utils.c.

                                                                   {
  if (!source->name)
    return (0);
  free(source->name);
  if (!source->filename)
    return (0);
  free(source->filename);
  if (source->path)
    free(source->path);
  if (source->description)
    free(source->description);
  if (source->contents)
    free(source->contents);
  SDDS_ZeroMemory(source, sizeof(*source));
  free(source);
  return (1);
}

SDDS_FreeColumnDefinition()

epicsShareFuncSDDS int32_t SDDS_FreeColumnDefinition ( COLUMN_DEFINITION * source )

extern

Frees memory allocated for a column definition.

This function deallocates all memory associated with a COLUMN_DEFINITION structure, including its string fields. After freeing, the structure is zeroed out to prevent dangling pointers.

Parameters

[in]

source

Pointer to the COLUMN_DEFINITION structure to be freed.

Returns

Returns 1 on successful deallocation. Returns 0 if the source is NULL or if required fields are missing.

Note

After calling this function, the source pointer becomes invalid and should not be used.

See also

SDDS_CopyColumnDefinition

SDDS_Free

Definition at line 1108 of file SDDS_utils.c.

                                                             {
  if (!source || !source->name)
    return (0);
  free(source->name);
  if (source->symbol)
    free(source->symbol);
  if (source->units)
    free(source->units);
  if (source->description)
    free(source->description);
  if (source->format_string)
    free(source->format_string);
  SDDS_ZeroMemory(source, sizeof(*source));
  free(source);
  return (1);
}

SDDS_FreeMatrix()

epicsShareFuncSDDS void SDDS_FreeMatrix ( void ** ptr, int64_t dim1 )

extern

Frees memory allocated for a two-dimensional matrix.

This function deallocates a two-dimensional matrix by freeing each row individually followed by the matrix pointer itself.

Parameters

[in]	ptr	Pointer to the two-dimensional matrix to be freed.
[in]	dim1	The number of rows in the matrix.

Note

• The function assumes that the matrix was allocated using SDDS_AllocateMatrix or similar memory allocation functions.

See also

SDDS_AllocateMatrix

free

Definition at line 2874 of file SDDS_utils.c.

                                               {
  int64_t i;
  if (!ptr)
    return;
  for (i = 0; i < dim1; i++)
    free(ptr[i]);
  free(ptr);
}

SDDS_FreeParameterDefinition()

epicsShareFuncSDDS int32_t SDDS_FreeParameterDefinition ( PARAMETER_DEFINITION * source )

extern

Frees memory allocated for a parameter definition.

This function deallocates all memory associated with a PARAMETER_DEFINITION structure, including its string fields. After freeing, the structure is zeroed out to prevent dangling pointers.

Parameters

[in]

source

Pointer to the PARAMETER_DEFINITION structure to be freed.

Returns

Returns 1 on successful deallocation. Returns 0 if the source is NULL or if required fields are missing.

Note

After calling this function, the source pointer becomes invalid and should not be used.

See also

SDDS_CopyParameterDefinition

SDDS_Free

Definition at line 1205 of file SDDS_utils.c.

                                                                   {
  if (!source || !source->name)
    return (0);
  free(source->name);
  if (source->symbol)
    free(source->symbol);
  if (source->units)
    free(source->units);
  if (source->description)
    free(source->description);
  if (source->format_string)
    free(source->format_string);
  if (source->fixed_value)
    free(source->fixed_value);
  SDDS_ZeroMemory(source, sizeof(*source));
  free(source);
  return (1);
}

SDDS_FreeStringArray()

epicsShareFuncSDDS int32_t SDDS_FreeStringArray ( char ** string, int64_t strings )

extern

Frees an array of strings by deallocating each individual string.

This function iterates through an array of strings, freeing each non-NULL string and setting its pointer to NULL to prevent dangling references.

Parameters

[in,out]	string	Array of strings to be freed.
[in]	strings	The number of elements in the string array.

Returns

• Returns 1 if the array is successfully freed.
• Returns 0 if the string pointer is NULL.

Note

• After calling this function, all string pointers within the array are set to NULL.

See also

SDDS_Free

free

Definition at line 2931 of file SDDS_utils.c.

                                                             {
  int64_t i;
  if (!string)
    return 0;
  for (i = 0; i < strings; i++)
    if (string[i]) {
      free(string[i]);
      string[i] = NULL;
    }
  return 1;
}

SDDS_FreeStringData()

epicsShareFuncSDDS int32_t SDDS_FreeStringData ( SDDS_DATASET * SDDS_dataset )

extern

Frees all allocated string data in the SDDS dataset.

This function frees any strings allocated for parameters, arrays, and columns within the SDDS dataset. It is typically called during termination to clean up allocated memory.

Parameters

SDDS_dataset

The SDDS dataset to free string data from.

Returns

Returns 1 on success, 0 on failure.

Definition at line 1397 of file SDDS_input.c.

                                                        {
  SDDS_LAYOUT *layout;
  char **ptr;
  int64_t i, j;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_Terminate"))
    return (0);
  layout = &SDDS_dataset->original_layout;
 
  if (SDDS_dataset->parameter) {
    for (i = 0; i < layout->n_parameters; i++) {
      if (layout->parameter_definition[i].type == SDDS_STRING) {
        free(*(char **)(SDDS_dataset->parameter[i]));
        *(char **)(SDDS_dataset->parameter[i]) = NULL;
      }
    }
  }
  if (SDDS_dataset->array) {
    for (i = 0; i < layout->n_arrays; i++) {
      if (layout->array_definition[i].type == SDDS_STRING) {
        for (j = 0; j < SDDS_dataset->array[i].elements; j++)
          if (((char **)SDDS_dataset->array[i].data)[j]) {
            free(((char **)SDDS_dataset->array[i].data)[j]);
            ((char **)SDDS_dataset->array[i].data)[j] = NULL;
          }
      }
    }
  }
  if (SDDS_dataset->data) {
    for (i = 0; i < layout->n_columns; i++)
      if (SDDS_dataset->data[i]) {
        if (layout->column_definition[i].type == SDDS_STRING) {
          ptr = (char **)SDDS_dataset->data[i];
          for (j = 0; j < SDDS_dataset->n_rows_allocated; j++, ptr++)
            if (*ptr) {
              free(*ptr);
              *ptr = NULL;
            }
        }
      }
  }
  return (1);
}

SDDS_GetArray()

epicsShareFuncSDDS SDDS_ARRAY * SDDS_GetArray ( SDDS_DATASET * SDDS_dataset, char * array_name, SDDS_ARRAY * memory )

extern

Retrieves an array from the current data table of an SDDS dataset.

This function returns a pointer to a SDDS_ARRAY structure containing the data and other information about a specified array within the current data table of an SDDS dataset. The function can either populate a provided SDDS_ARRAY structure or allocate a new one if memory is NULL.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
array_name	A null-terminated string specifying the name of the SDDS array to retrieve.
memory	Optional pointer to an existing SDDS_ARRAY structure where the array information will be stored. If NULL, a new SDDS_ARRAY structure is allocated and returned.

Returns

On success, returns a pointer to a SDDS_ARRAY structure containing the array data and metadata. If memory is not NULL, the function populates the provided structure. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, unrecognized array name, memory allocation failure).
Non-NULL	Pointer to a SDDS_ARRAY structure containing the array data and metadata.

Note

• The caller is responsible for freeing the allocated memory for the SDDS_ARRAY structure if memory is NULL.
• The definition field in the returned structure points to the internal copy of the array definition.

See also

SDDS_GetArrayInDoubles, SDDS_GetArrayInString, SDDS_GetArrayInLong

Definition at line 4210 of file SDDS_extract.c.

                                                                                            {
  int32_t index, type, size;
  SDDS_ARRAY *copy, *original;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArray"))
    return (NULL);
  if (!array_name) {
    SDDS_SetError("Unable to get array--array name pointer is NULL (SDDS_GetArray)");
    return (NULL);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to get array--array name is unrecognized (SDDS_GetArray)");
    return (NULL);
  }
  if (memory)
    copy = memory;
  else if (!(copy = (SDDS_ARRAY *)calloc(1, sizeof(*copy)))) {
    SDDS_SetError("Unable to get array--allocation failure (SDDS_GetArray)");
    return (NULL);
  }
  original = SDDS_dataset->array + index;
  if (copy->definition && !SDDS_FreeArrayDefinition(copy->definition)) {
    SDDS_SetError("Unable to get array--array definition corrupted (SDDS_GetArray)");
    return (NULL);
  }
  if (!SDDS_CopyArrayDefinition(&copy->definition, original->definition)) {
    SDDS_SetError("Unable to get array--array definition missing (SDDS_GetArray)");
    return (NULL);
  }
  type = copy->definition->type;
  size = SDDS_type_size[copy->definition->type - 1];
  if (!(copy->dimension = SDDS_Realloc(copy->dimension, sizeof(*copy->dimension) * copy->definition->dimensions))) {
    SDDS_SetError("Unable to get array--allocation failure (SDDS_GetArray)");
    return (NULL);
  }
  memcpy((void *)copy->dimension, (void *)original->dimension, sizeof(*copy->dimension) * copy->definition->dimensions);
  if (!(copy->elements = original->elements))
    return (copy);
  if (!(copy->data = SDDS_Realloc(copy->data, size * original->elements))) {
    SDDS_SetError("Unable to get array--allocation failure (SDDS_GetArray)");
    return (NULL);
  }
 
  if (copy->definition->type != SDDS_STRING)
    memcpy(copy->data, original->data, size * copy->elements);
  else if (!SDDS_CopyStringArray((char **)copy->data, (char **)original->data, original->elements)) {
    SDDS_SetError("Unable to get array--string copy failure (SDDS_GetArray)");
    return (NULL);
  }
 
  /* should free existing subpointers here, but probably not worth the trouble */
  if (copy->pointer && copy->definition->dimensions != 1)
    free(copy->pointer);
  if (!(copy->pointer = SDDS_MakePointerArray(copy->data, type, copy->definition->dimensions, copy->dimension))) {
    SDDS_SetError("Unable to get array--couldn't make pointer array (SDDS_GetArray)");
    return (NULL);
  }
  return (copy);
}

SDDS_GetArrayDefinition()

epicsShareFuncSDDS ARRAY_DEFINITION * SDDS_GetArrayDefinition ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the definition of a specified array from the SDDS dataset.

This function searches for an array by its name within the provided SDDS dataset. If found, it creates a copy of the array's definition and returns a pointer to it. The returned pointer should be freed by the caller using SDDS_FreeArrayDefinition to avoid memory leaks.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the array to retrieve.

Returns

On success, returns a pointer to a newly allocated ARRAY_DEFINITION structure containing the array's information. On failure (e.g., if the array is not found or a copy fails), returns NULL and records an error message.

Note

The caller is responsible for freeing the returned ARRAY_DEFINITION pointer using SDDS_FreeArrayDefinition.

See also

SDDS_CopyArrayDefinition

SDDS_FreeArrayDefinition

SDDS_SetError

Definition at line 1240 of file SDDS_utils.c.

                                                                                  {
  int32_t i;
  ARRAY_DEFINITION *arraydef;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayDefinition"))
    return (NULL);
  if (!name) {
    SDDS_SetError("Unable to get array definition--name is NULL (SDDS_GetArrayDefinition)");
    return (NULL);
  }
  if ((i = SDDS_GetArrayIndex(SDDS_dataset, name)) < 0)
    return NULL;
  if (!SDDS_CopyArrayDefinition(&arraydef, SDDS_dataset->layout.array_definition + i)) {
    SDDS_SetError("Unable to get array definition--copy failure  (SDDS_GetArrayDefinition)");
    return (NULL);
  }
  return (arraydef);
}

SDDS_GetArrayIndex()

epicsShareFuncSDDS int32_t SDDS_GetArrayIndex ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the index of a named array in the SDDS dataset.

This function searches for an array by its name within the provided SDDS dataset and returns its index. The index can then be used with other routines for faster access to the array's data or metadata.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the array whose index is desired.

Returns

On success, returns a non-negative integer representing the index of the array. On failure (e.g., if the array is not found), returns -1 and records an error message.

See also

SDDS_GetArrayDefinition

SDDS_SetError

Definition at line 1433 of file SDDS_utils.c.

                                                                   {
  int32_t i;
  SORTED_INDEX key;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayIndex"))
    return (-1);
  if (!name) {
    SDDS_SetError("Unable to get array index--name is NULL (SDDS_GetArrayIndex)");
    return (-1);
  }
  key.name = name;
  if ((i = binaryIndexSearch((void **)SDDS_dataset->layout.array_index, SDDS_dataset->layout.n_arrays, &key, SDDS_CompareIndexedNames, 0)) < 0)
    return -1;
  return SDDS_dataset->layout.array_index[i]->index;
}

SDDS_GetArrayInDoubles()

epicsShareFuncSDDS double * SDDS_GetArrayInDoubles ( SDDS_DATASET * SDDS_dataset, char * array_name, int32_t * values )

extern

Retrieves an array from the current data table of an SDDS dataset and converts its elements to doubles.

This function extracts the specified array from the provided SDDS dataset and converts each of its elements into a double value. It ensures that the array is of a compatible numeric type before performing the conversion.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
array_name	A null-terminated string specifying the name of the SDDS array to retrieve and convert.
values	Pointer to an integer where the number of elements in the array will be stored upon successful completion.

Returns

On success, returns a pointer to an array of double values representing the SDDS array elements. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, unrecognized array name, incompatible array type, memory allocation failure).
Non-NULL	Pointer to an array of double values representing the SDDS array elements.

Note

• The caller is responsible for freeing the allocated memory for the returned double array.
• The function does not handle string-type arrays; attempting to retrieve a string array will result in an error.

See also

SDDS_GetArray, SDDS_GetArrayInString, SDDS_GetArrayInLong

Definition at line 4414 of file SDDS_extract.c.

                                                                                              {
  int32_t index, type, i, elements;
  SDDS_ARRAY *original;
  double *data;
  void *rawData;
 
  *values = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayInDoubles"))
    return (NULL);
  if (!array_name) {
    SDDS_SetError("Unable to get array--array name pointer is NULL (SDDS_GetArrayInDoubles)");
    return (NULL);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to get array--array name is unrecognized (SDDS_GetArrayInDoubles)");
    return (NULL);
  }
  original = SDDS_dataset->array + index;
  if ((type = original->definition->type) == SDDS_STRING) {
    SDDS_SetError("Unable to get array--string type (SDDS_GetArrayInDoubles)");
    return (NULL);
  }
  elements = original->elements;
  if (!(data = SDDS_Malloc(sizeof(*data) * elements))) {
    SDDS_SetError("Unable to get array--allocation failure (SDDS_GetArrayInDoubles)");
    return (NULL);
  }
  rawData = original->data;
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = 0; i < elements; i++) {
      data[i] = ((long double *)rawData)[i];
    }
    break;
  case SDDS_DOUBLE:
    for (i = 0; i < elements; i++) {
      data[i] = ((double *)rawData)[i];
    }
    break;
  case SDDS_FLOAT:
    for (i = 0; i < elements; i++) {
      data[i] = ((float *)rawData)[i];
    }
    break;
  case SDDS_LONG64:
    for (i = 0; i < elements; i++) {
      data[i] = ((int64_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG64:
    for (i = 0; i < elements; i++) {
      data[i] = ((uint64_t *)rawData)[i];
    }
    break;
  case SDDS_LONG:
    for (i = 0; i < elements; i++) {
      data[i] = ((int32_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG:
    for (i = 0; i < elements; i++) {
      data[i] = ((uint32_t *)rawData)[i];
    }
    break;
  case SDDS_SHORT:
    for (i = 0; i < elements; i++) {
      data[i] = ((short *)rawData)[i];
    }
    break;
  case SDDS_USHORT:
    for (i = 0; i < elements; i++) {
      data[i] = ((unsigned short *)rawData)[i];
    }
    break;
  case SDDS_CHARACTER:
    for (i = 0; i < elements; i++) {
      data[i] = ((char *)rawData)[i];
    }
    break;
  }
  *values = elements;
  return data;
}

SDDS_GetArrayInformation()

epicsShareFuncSDDS int32_t SDDS_GetArrayInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Retrieves information about a specified array in the SDDS dataset.

This function is the preferred alternative to SDDS_GetArrayDefinition. It allows you to obtain information about a specific field of an array, either by the array's name or index.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field for which information is requested.
[out]	memory	Pointer to a variable where the retrieved information will be stored. The variable should be of type data_type*, where data_type corresponds to the type of the requested information. For STRING information, use char*. If memory is NULL, the function will verify the existence and type of the information, returning the data type without storing any data.
[in]	mode	Specifies how to identify the array. Valid values are: SDDS_GET_BY_NAME: Identify the array by its name. Requires an additional argument of type char* (array name). SDDS_GET_BY_INDEX: Identify the array by its index. Requires an additional argument of type int32_t (array index).

Returns

On success, returns the SDDS data type of the requested information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the array name or index based on the mode parameter.

See also

SDDS_GetArrayDefinition

Definition at line 192 of file SDDS_info.c.

                                                                                                                {
  int32_t field_index, type, array_index;
  ARRAY_DEFINITION *arraydef;
  char *array_name;
  va_list argptr;
  int32_t retval;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_GetArrayInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_GET_BY_INDEX) {
    if ((array_index = va_arg(argptr, int32_t)) < 0 || array_index >= SDDS_dataset->layout.n_arrays) {
      SDDS_SetError("Invalid array index passed. (SDDS_GetArrayInformation)");
      retval = 0;
    }
  } else {
    if (!(array_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL array name passed. (SDDS_GetArrayInformation)");
      retval = 0;
    }
    if ((array_index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
      SDDS_SetError("Unknown array name given (SDDS_GetArrayInformation)");
      retval = 0;
    }
  }
  arraydef = SDDS_dataset->layout.array_definition + array_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_ARRAY_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_ArrayFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_ARRAY_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_GetArrayInformation)");
    return (0);
  }
  type = SDDS_ArrayFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString((char **)memory, *((char **)((char *)arraydef + SDDS_ArrayFieldInformation[field_index].offset)))) {
      SDDS_SetError("Unable to copy field data (SDDS_GetArrayInformation)");
      return (0);
    }
  } else
    memcpy(memory, (char *)arraydef + SDDS_ArrayFieldInformation[field_index].offset, SDDS_type_size[type - 1]);
  return (type);
}

SDDS_GetArrayInLong()

epicsShareFuncSDDS int32_t * SDDS_GetArrayInLong ( SDDS_DATASET * SDDS_dataset, char * array_name, int32_t * values )

extern

Retrieves an array from the current data table of an SDDS dataset and converts its elements to 32-bit integers.

This function extracts the specified array from the provided SDDS dataset and converts each of its elements into a 32-bit integer (int32_t). It ensures that the array is of a compatible numeric type before performing the conversion.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
array_name	A null-terminated string specifying the name of the SDDS array to retrieve and convert.
values	Pointer to an integer where the number of elements in the array will be stored upon successful completion.

Returns

On success, returns a pointer to an array of int32_t values representing the SDDS array elements. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, unrecognized array name, incompatible array type, memory allocation failure).
Non-NULL	Pointer to an array of int32_t values representing the SDDS array elements.

Note

• The caller is responsible for freeing the allocated memory for the returned int32_t array.
• The function does not handle string-type arrays; attempting to retrieve a string array will result in an error.

See also

SDDS_GetArray, SDDS_GetArrayInDoubles, SDDS_GetArrayInString

Definition at line 4519 of file SDDS_extract.c.

                                                                                            {
  int32_t index, type, i, elements;
  SDDS_ARRAY *original;
  int32_t *data;
  void *rawData;
 
  *values = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayInLong"))
    return (NULL);
  if (!array_name) {
    SDDS_SetError("Unable to get array--array name pointer is NULL (SDDS_GetArrayInLong)");
    return (NULL);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to get array--array name is unrecognized (SDDS_GetArrayInLong)");
    return (NULL);
  }
  original = SDDS_dataset->array + index;
  if ((type = original->definition->type) == SDDS_STRING) {
    SDDS_SetError("Unable to get array--string type (SDDS_GetArrayInLong)");
    return (NULL);
  }
  elements = original->elements;
  if (!(data = SDDS_Malloc(sizeof(*data) * elements))) {
    SDDS_SetError("Unable to get array--allocation failure (SDDS_GetArrayInLong)");
    return (NULL);
  }
  rawData = original->data;
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = 0; i < elements; i++) {
      data[i] = ((long double *)rawData)[i];
    }
    break;
  case SDDS_DOUBLE:
    for (i = 0; i < elements; i++) {
      data[i] = ((double *)rawData)[i];
    }
    break;
  case SDDS_FLOAT:
    for (i = 0; i < elements; i++) {
      data[i] = ((float *)rawData)[i];
    }
    break;
  case SDDS_LONG64:
    for (i = 0; i < elements; i++) {
      data[i] = ((int64_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG64:
    for (i = 0; i < elements; i++) {
      data[i] = ((uint64_t *)rawData)[i];
    }
    break;
  case SDDS_LONG:
    for (i = 0; i < elements; i++) {
      data[i] = ((int32_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG:
    for (i = 0; i < elements; i++) {
      data[i] = ((uint32_t *)rawData)[i];
    }
    break;
  case SDDS_SHORT:
    for (i = 0; i < elements; i++) {
      data[i] = ((short *)rawData)[i];
    }
    break;
  case SDDS_USHORT:
    for (i = 0; i < elements; i++) {
      data[i] = ((unsigned short *)rawData)[i];
    }
    break;
  case SDDS_CHARACTER:
    for (i = 0; i < elements; i++) {
      data[i] = ((char *)rawData)[i];
    }
    break;
  }
  *values = elements;
  return data;
}

SDDS_GetArrayInString()

epicsShareFuncSDDS char ** SDDS_GetArrayInString ( SDDS_DATASET * SDDS_dataset, char * array_name, int32_t * values )

extern

Retrieves an array from the current data table of an SDDS dataset and converts its elements to strings.

This function extracts the specified array from the provided SDDS dataset and converts each of its elements into a null-terminated string representation. The conversion respects the data type of the array elements, ensuring accurate string formatting.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
array_name	A null-terminated string specifying the name of the SDDS array to retrieve and convert.
values	Pointer to an integer where the number of elements in the array will be stored upon successful completion.

Returns

On success, returns a pointer to an array of null-terminated strings (char **). Each string represents an element of the original SDDS array. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, unrecognized array name, memory allocation failure).
Non-NULL	Pointer to an array of strings representing the SDDS array elements.

Note

• The caller is responsible for freeing each string in the returned array as well as the array itself.
• The function handles different data types, including numeric types and strings, ensuring proper formatting for each type.

See also

SDDS_GetArray, SDDS_GetArrayInDoubles, SDDS_GetArrayInLong

Definition at line 4292 of file SDDS_extract.c.

                                                                                            {
  int32_t index, type, i, elements;
  SDDS_ARRAY *original;
  char **data;
  char buffer[SDDS_MAXLINE];
  void *rawData;
 
  *values = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayInString"))
    return (NULL);
  if (!array_name) {
    SDDS_SetError("Unable to get array--array name pointer is NULL (SDDS_GetArrayInString)");
    return (NULL);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to get array--array name is unrecognized (SDDS_GetArrayInString)");
    return (NULL);
  }
  original = SDDS_dataset->array + index;
  type = original->definition->type;
  elements = original->elements;
  if (!(data = (char **)SDDS_Malloc(sizeof(*data) * elements))) {
    SDDS_SetError("Unable to get array--allocation failure (SDDS_GetArrayInString)");
    return (NULL);
  }
  rawData = original->data;
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = 0; i < elements; i++) {
      if (LDBL_DIG == 18) {
        sprintf(buffer, "%22.18Le", ((long double *)rawData)[i]);
      } else {
        sprintf(buffer, "%22.15Le", ((long double *)rawData)[i]);
      }
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_DOUBLE:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%22.15le", ((double *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_FLOAT:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%15.8e", ((float *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_LONG64:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%" PRId64, ((int64_t *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_ULONG64:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%" PRIu64, ((uint64_t *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_LONG:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%" PRId32, ((int32_t *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_ULONG:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%" PRIu32, ((uint32_t *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_SHORT:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%hd", ((short *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_USHORT:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%hu", ((unsigned short *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_CHARACTER:
    for (i = 0; i < elements; i++) {
      sprintf(buffer, "%c", ((char *)rawData)[i]);
      SDDS_CopyString(&data[i], buffer);
    }
    break;
  case SDDS_STRING:
    for (i = 0; i < elements; i++) {
      SDDS_CopyString(&data[i], ((char **)rawData)[i]);
    }
    break;
  }
  *values = elements;
  return data;
}

SDDS_GetArrayNames()

epicsShareFuncSDDS char ** SDDS_GetArrayNames ( SDDS_DATASET * SDDS_dataset, int32_t * number )

extern

Retrieves the names of all arrays in the SDDS dataset.

This function allocates and returns an array of NULL-terminated strings containing the names of the arrays in the provided SDDS_dataset.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[out]	number	Pointer to an int32_t variable where the number of retrieved array names will be stored.

Returns

• Returns a pointer to an array of NULL-terminated strings containing the array names on success.
• Returns NULL on failure (e.g., if the dataset is invalid or memory allocation fails) and records an error message.

Note

The caller is responsible for freeing the memory allocated for the returned array and its strings using SDDS_FreeStringArray or similar functions.

See also

SDDS_CheckDataset

SDDS_Malloc

SDDS_CopyString

SDDS_SetError

Definition at line 2605 of file SDDS_utils.c.

                                                                       {
  int32_t i;
  char **name;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayNames"))
    return (NULL);
  *number = SDDS_dataset->layout.n_arrays;
  if (!(name = (char **)SDDS_Malloc(sizeof(*name) * SDDS_dataset->layout.n_arrays))) {
    SDDS_SetError("Unable to get array names--allocation failure (SDDS_GetArrayNames)");
    return (NULL);
  }
  for (i = 0; i < SDDS_dataset->layout.n_arrays; i++) {
    if (!SDDS_CopyString(name + i, SDDS_dataset->layout.array_definition[i].name)) {
      free(name);
      return (NULL);
    }
  }
  return (name);
}

SDDS_GetArrayType()

epicsShareFuncSDDS int32_t SDDS_GetArrayType ( SDDS_DATASET * SDDS_dataset, int32_t index )

extern

Retrieves the data type of an array in the SDDS dataset by its index.

This function returns the SDDS data type of the specified array within the dataset. The data type corresponds to one of the predefined SDDS type constants, such as SDDS_LONGDOUBLE, SDDS_DOUBLE, SDDS_FLOAT, etc.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	index	The zero-based index of the array whose data type is to be retrieved. The index should be obtained from SDDS_DefineArray or SDDS_GetArrayIndex.

Returns

On success, returns the SDDS data type of the array as an int32_t. On failure (e.g., if the index is out of range or the dataset is invalid), returns 0 and records an error message.

Note

The function does not perform type validation beyond checking the index range. It assumes that the dataset's array definitions are correctly initialized.

See also

SDDS_GetArrayIndex

SDDS_SetError

Definition at line 2268 of file SDDS_utils.c.

                                                                     {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetArrayType"))
    return (0);
  if (index < 0 || index >= SDDS_dataset->layout.n_arrays) {
    SDDS_SetError("Unable to get array type--array index is out of range (SDDS_GetArrayType)");
    return (0);
  }
  return (SDDS_dataset->layout.array_definition[index].type);
}

SDDS_GetAssociateDefinition()

epicsShareFuncSDDS ASSOCIATE_DEFINITION * SDDS_GetAssociateDefinition ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the definition of a specified associate from the SDDS dataset.

This function searches for an associate by its name within the provided SDDS dataset. If found, it creates a copy of the associate's definition and returns a pointer to it. The returned pointer should be freed by the caller using SDDS_FreeAssociateDefinition to avoid memory leaks.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the associate to retrieve.

Returns

On success, returns a pointer to a newly allocated ASSOCIATE_DEFINITION structure containing the associate's information. On failure (e.g., if the associate is not found or a copy fails), returns NULL and records an error message.

Note

The caller is responsible for freeing the returned ASSOCIATE_DEFINITION pointer using SDDS_FreeAssociateDefinition.

See also

SDDS_CopyAssociateDefinition

SDDS_FreeAssociateDefinition

SDDS_SetError

Definition at line 949 of file SDDS_utils.c.

                                                                                          {
  int32_t i;
  ASSOCIATE_DEFINITION *assdef;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetAssociateDefinition"))
    return (NULL);
  if (!name) {
    SDDS_SetError("Unable to get associate definition--name is NULL (SDDS_GetAssociateDefinition)");
    return (NULL);
  }
  for (i = 0; i < SDDS_dataset->layout.n_associates; i++) {
    if (strcmp(SDDS_dataset->layout.associate_definition[i].name, name) == 0) {
      if (!SDDS_CopyAssociateDefinition(&assdef, SDDS_dataset->layout.associate_definition + i)) {
        SDDS_SetError("Unable to get associate definition--copy failure  (SDDS_GetAssociateDefinition)");
        return (NULL);
      }
      return (assdef);
    }
  }
  return (NULL);
}

SDDS_GetAssociateIndex()

epicsShareFuncSDDS int32_t SDDS_GetAssociateIndex ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the index of a named associate in the SDDS dataset.

This function searches for an associate by its name within the provided SDDS dataset and returns its index. The index can then be used with other routines for faster access to the associate's data or metadata.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the associate whose index is desired.

Returns

On success, returns a non-negative integer representing the index of the associate. On failure (e.g., if the associate is not found), returns -1 and records an error message.

See also

SDDS_GetAssociateDefinition

SDDS_SetError

Definition at line 1462 of file SDDS_utils.c.

                                                                       {
  int32_t i;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetAssociateIndex"))
    return (-1);
  if (!name) {
    SDDS_SetError("Unable to get associate index--name is NULL (SDDS_GetAssociateIndex)");
    return (-1);
  }
  for (i = 0; i < SDDS_dataset->layout.n_associates; i++) {
    if (strcmp(SDDS_dataset->layout.associate_definition[i].name, name) == 0)
      return (i);
  }
  return (-1);
}

SDDS_GetAssociateInformation()

epicsShareFuncSDDS int32_t SDDS_GetAssociateInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Retrieves information about a specified associate in the SDDS dataset.

This function allows you to obtain information about a specific field of an associate, either by the associate's name or index.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field for which information is requested.
[out]	memory	Pointer to a variable where the retrieved information will be stored. The variable should be of type data_type*, where data_type corresponds to the type of the requested information. For STRING information, use char*. If memory is NULL, the function will verify the existence and type of the information, returning the data type without storing any data.
[in]	mode	Specifies how to identify the associate. Valid values are: SDDS_GET_BY_NAME: Identify the associate by its name. Requires an additional argument of type char* (associate name). SDDS_GET_BY_INDEX: Identify the associate by its index. Requires an additional argument of type int32_t (associate index).

Returns

On success, returns the SDDS data type of the requested information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the associate name or index based on the mode parameter.

See also

SDDS_GetAssociateDefinition

Definition at line 267 of file SDDS_info.c.

                                                                                                                    {
  int32_t field_index, type, associate_index;
  ASSOCIATE_DEFINITION *associatedef;
  char *associate_name;
  va_list argptr;
  int32_t retval;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetAssociateInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_GetAssociateInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_GET_BY_INDEX) {
    if ((associate_index = va_arg(argptr, int32_t)) < 0 || associate_index >= SDDS_dataset->layout.n_associates) {
      SDDS_SetError("Invalid associate index passed. (SDDS_GetAssociateInformation)");
      retval = 0;
    }
  } else {
    if (!(associate_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL associate name passed. (SDDS_GetAssociateInformation)");
      retval = 0;
    }
    if ((associate_index = SDDS_GetAssociateIndex(SDDS_dataset, associate_name)) < 0) {
      SDDS_SetError("Unknown associate name given (SDDS_GetAssociateInformation)");
      retval = 0;
    }
  }
  associatedef = SDDS_dataset->layout.associate_definition + associate_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_ASSOCIATE_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_AssociateFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_ASSOCIATE_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_GetAssociateInformation)");
    return (0);
  }
  type = SDDS_AssociateFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString((char **)memory, *((char **)((char *)associatedef + SDDS_AssociateFieldInformation[field_index].offset)))) {
      SDDS_SetError("Unable to copy field data (SDDS_GetAssociateInformation)");
      return (0);
    }
  } else
    memcpy(memory, (char *)associatedef + SDDS_AssociateFieldInformation[field_index].offset, SDDS_type_size[type - 1]);
  return (type);
}

SDDS_GetAssociateNames()

epicsShareFuncSDDS char ** SDDS_GetAssociateNames ( SDDS_DATASET * SDDS_dataset, int32_t * number )

extern

Retrieves the names of all associates in the SDDS dataset.

This function allocates and returns an array of NULL-terminated strings containing the names of the associates in the provided SDDS_dataset.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[out]	number	Pointer to an int32_t variable where the number of retrieved associate names will be stored.

Returns

• Returns a pointer to an array of NULL-terminated strings containing the associate names on success.
• Returns NULL on failure (e.g., if the dataset is invalid or memory allocation fails) and records an error message.

Note

The caller is responsible for freeing the memory allocated for the returned array and its strings using SDDS_FreeStringArray or similar functions.

See also

SDDS_CheckDataset

SDDS_Malloc

SDDS_CopyString

SDDS_SetError

Definition at line 2643 of file SDDS_utils.c.

                                                                           {
  int32_t i;
  char **name;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetAssociateNames"))
    return (NULL);
  if (!(name = (char **)SDDS_Malloc(sizeof(*name) * SDDS_dataset->layout.n_associates))) {
    SDDS_SetError("Unable to get associate names--allocation failure (SDDS_GetAssociateNames)");
    return (NULL);
  }
  *number = SDDS_dataset->layout.n_associates;
  for (i = 0; i < SDDS_dataset->layout.n_associates; i++) {
    if (!SDDS_CopyString(name + i, SDDS_dataset->layout.associate_definition[i].name)) {
      free(name);
      return (NULL);
    }
  }
  return (name);
}

SDDS_GetCastMatrixOfRows()

epicsShareFuncSDDS void * SDDS_GetCastMatrixOfRows ( SDDS_DATASET * SDDS_dataset, int64_t * n_rows, int32_t sddsType )

extern

Retrieves all rows marked as "of interest" as a matrix, casting each value to a specified numerical type.

This function extracts all rows that are flagged as "of interest" within the current data table of a dataset and casts each value to a specified numerical type. It processes only those columns that are flagged as "of interest" and returns the data as a matrix, where each row is an array of casted values corresponding to the selected columns.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
n_rows	Pointer to an int64_t variable where the number of rows retrieved will be stored.
sddsType	Integer constant representing the desired data type for casting (e.g., SDDS_DOUBLE, SDDS_FLOAT, etc.). Must be a valid numerical type as defined by SDDS.

Returns

• Pointer to an array of pointers, where each pointer references a row's data array cast to the specified type.
• NULL if an error occurs (e.g., invalid dataset, no columns selected, inconsistent data types among selected columns, non-numeric sddsType, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks. This includes freeing each individual row array followed by the array of pointers itself.
• All selected columns must have numerical data types. If any selected column is non-numeric, the function will fail.
• Ensure that sddsType is a valid numerical type supported by SDDS.

Note

• The number of rows retrieved is stored in the variable pointed to by n_rows.
• This function performs type casting using SDDS_CastValue. If casting fails for any value, the function will terminate and return NULL.
• If the dataset's memory mode for the columns is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the columns may be freed after access.

See also

• SDDS_GetMatrixOfRows
• SDDS_CastValue
• SDDS_GetRowType
• SDDS_SetColumnFlags
• SDDS_CountRowsOfInterest

Definition at line 2344 of file SDDS_extract.c.

                                                                                              {
  void **data;
  int32_t size;
  int64_t i, j, k;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetCastMatrixOfRows"))
    return (NULL);
  if (!SDDS_NUMERIC_TYPE(sddsType)) {
    SDDS_SetError("Unable to get matrix of rows--no columns selected (SDDS_GetCastMatrixOfRows)");
    return NULL;
  }
  if (SDDS_dataset->n_of_interest <= 0) {
    SDDS_SetError("Unable to get matrix of rows--no columns selected (SDDS_GetCastMatrixOfRows)");
    return (NULL);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_GetCastMatrixOfRows"))
    return (NULL);
  size = SDDS_type_size[sddsType - 1];
  if ((*n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get matrix of rows--no rows of interest (SDDS_GetCastMatrixOfRows)");
    return (NULL);
  }
  if (!(data = (void **)SDDS_Malloc(sizeof(*data) * (*n_rows)))) {
    SDDS_SetError("Unable to get matrix of rows--memory allocation failure (SDDS_GetCastMatrixOfRows)");
    return (NULL);
  }
  for (i = 0; i < SDDS_dataset->n_of_interest; i++) {
    if (!SDDS_NUMERIC_TYPE(SDDS_dataset->layout.column_definition[SDDS_dataset->column_order[i]].type)) {
      SDDS_SetError("Unable to get matrix of rows--not all columns are numeric (SDDS_GetCastMatrixOfRows)");
      return NULL;
    }
  }
  for (j = k = 0; j < SDDS_dataset->n_rows; j++) {
    if (SDDS_dataset->row_flag[j]) {
      if (!(data[k] = SDDS_Malloc(size * SDDS_dataset->n_of_interest))) {
        SDDS_SetError("Unable to get matrix of rows--memory allocation failure (SDDS_GetCastMatrixOfRows)");
        return (NULL);
      }
      for (i = 0; i < SDDS_dataset->n_of_interest; i++)
        SDDS_CastValue(SDDS_dataset->data[SDDS_dataset->column_order[i]], j, SDDS_dataset->layout.column_definition[SDDS_dataset->column_order[i]].type, sddsType, (char *)data[k] + i * sizeof(double));
      k++;
    }
  }
  return (data);
}

SDDS_GetColumn()

epicsShareFuncSDDS void * SDDS_GetColumn ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves a copy of the data for a specified column, including only rows marked as "of interest".

This function returns a newly allocated array containing data from the specified column for all rows that are flagged as "of interest". The data type of the returned array matches the column's data type.

For columns of type SDDS_STRING, the returned array is of type char**, with each element being a dynamically allocated string.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column to retrieve.

Returns

• Pointer to the data array on success. The type of the array corresponds to the column's data type.
• NULL on failure, with an error message recorded (e.g., unrecognized column name, memory allocation failure, no rows of interest).

Warning

The caller is responsible for freeing the allocated memory to avoid memory leaks. For SDDS_STRING types, each string within the array should be freed individually, followed by the array itself.

Note

• The number of rows in the returned array can be obtained using SDDS_CountRowsOfInterest.
• If the column's memory mode is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data may be freed after access.

See also

SDDS_GetInternalColumn, SDDS_CountRowsOfInterest, SDDS_SetRowFlags

Definition at line 611 of file SDDS_extract.c.

                                                                    {
  int32_t size, type, index;
  int64_t i, j, n_rows;
  void *data;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumn"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetColumn)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetColumn)");
    return (NULL);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get column--data type undefined (SDDS_GetColumn)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if (!(data = SDDS_Malloc(size * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetColumn)");
    return (NULL);
  }
  for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
    if (SDDS_dataset->row_flag[i]) {
      if (type != SDDS_STRING)
        memcpy((char *)data + size * j++, (char *)SDDS_dataset->data[index] + size * i, size);
      else if (!SDDS_CopyString((char **)data + j++, ((char ***)SDDS_dataset->data)[index][i]))
        return (NULL);
    }
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetColumn)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetColumnDefinition()

epicsShareFuncSDDS COLUMN_DEFINITION * SDDS_GetColumnDefinition ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the definition of a specified column from the SDDS dataset.

This function searches for a column by its name within the provided SDDS dataset. If found, it creates a copy of the column's definition and returns a pointer to it. The returned pointer should be freed by the caller using SDDS_FreeColumnDefinition to avoid memory leaks.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the column to retrieve.

Returns

On success, returns a pointer to a newly allocated COLUMN_DEFINITION structure containing the column's information. On failure (e.g., if the column is not found or a copy fails), returns NULL and records an error message.

Note

The caller is responsible for freeing the returned COLUMN_DEFINITION pointer using SDDS_FreeColumnDefinition.

See also

SDDS_CopyColumnDefinition

SDDS_FreeColumnDefinition

SDDS_SetError

Definition at line 1044 of file SDDS_utils.c.

                                                                                    {
  int64_t i;
  COLUMN_DEFINITION *coldef;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnDefinition"))
    return (NULL);
  if (!name) {
    SDDS_SetError("Unable to get column definition--name is NULL (SDDS_GetColumnDefinition)");
    return (NULL);
  }
  if ((i = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0)
    return NULL;
  if (!SDDS_CopyColumnDefinition(&coldef, SDDS_dataset->layout.column_definition + i)) {
    SDDS_SetError("Unable to get column definition--copy failure  (SDDS_GetColumnDefinition)");
    return (NULL);
  }
  return (coldef);
}

SDDS_GetColumnIndex()

epicsShareFuncSDDS int32_t SDDS_GetColumnIndex ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the index of a named column in the SDDS dataset.

This function searches for a column by its name within the provided SDDS dataset and returns its index. The index can then be used with other routines for faster access to the column's data or metadata.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the column whose index is desired.

Returns

On success, returns a non-negative integer representing the index of the column. On failure (e.g., if the column is not found), returns -1 and records an error message.

See also

SDDS_GetColumnDefinition

SDDS_SetError

Definition at line 1375 of file SDDS_utils.c.

                                                                    {
  int64_t i;
  SORTED_INDEX key;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnIndex"))
    return (-1);
  if (!name) {
    SDDS_SetError("Unable to get column index--name is NULL (SDDS_GetColumnIndex)");
    return (-1);
  }
  key.name = name;
  if ((i = binaryIndexSearch((void **)SDDS_dataset->layout.column_index, SDDS_dataset->layout.n_columns, &key, SDDS_CompareIndexedNames, 0)) < 0)
    return -1;
  return SDDS_dataset->layout.column_index[i]->index;
}

SDDS_GetColumnInDoubles()

epicsShareFuncSDDS double * SDDS_GetColumnInDoubles ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves the data of a specified numerical column as an array of doubles, considering only rows marked as "of interest".

This function extracts data from a specified column within the current data table of a dataset. It processes only those rows that are flagged as "of interest" (i.e., have a non-zero acceptance flag). The extracted data is returned as a newly allocated array of double values.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which data is to be retrieved.

Returns

• Pointer to an array of double containing the data from the specified column for all rows marked as "of interest".
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, non-numeric column type, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks.
• This function assumes that the specified column contains numerical data. Attempting to retrieve data from a non-numeric column (excluding SDDS_CHARACTER) will result in an error.

Note

• The number of elements in the returned array corresponds to the number of rows marked as "of interest", which can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.

See also

• SDDS_GetColumnInLongDoubles
• SDDS_GetColumnInFloats
• SDDS_GetColumn
• SDDS_CountRowsOfInterest

Definition at line 872 of file SDDS_extract.c.

                                                                               {
  int32_t size, type, index;
  int64_t i, j, n_rows;
  double *data;
  void *rawData;
 
  j = 0;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnInDoubles"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetColumnInDoubles)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetColumnInDoubles)");
    return (NULL);
  }
  if ((type = SDDS_GetColumnType(SDDS_dataset, index)) <= 0 || (size = SDDS_GetTypeSize(type)) <= 0 || (!SDDS_NUMERIC_TYPE(type) && type != SDDS_CHARACTER)) {
    SDDS_SetError("Unable to get column--data size or type undefined or non-numeric (SDDS_GetColumnInDoubles)");
    return (NULL);
  }
  if (!(data = (double *)SDDS_Malloc(sizeof(double) * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetColumnInDoubles)");
    return (NULL);
  }
  rawData = SDDS_dataset->data[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((long double *)rawData)[i];
    }
    break;
  case SDDS_DOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((double *)rawData)[i];
    }
    break;
  case SDDS_FLOAT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((float *)rawData)[i];
    }
    break;
  case SDDS_LONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int32_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint32_t *)rawData)[i];
    }
    break;
  case SDDS_LONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int64_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint64_t *)rawData)[i];
    }
    break;
  case SDDS_SHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((short *)rawData)[i];
    }
    break;
  case SDDS_USHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((unsigned short *)rawData)[i];
    }
    break;
  case SDDS_CHARACTER:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((char *)rawData)[i];
    }
    break;
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetColumnInDoubles)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetColumnInFloats()

epicsShareFuncSDDS float * SDDS_GetColumnInFloats ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves the data of a specified numerical column as an array of floats, considering only rows marked as "of interest".

This function extracts data from a specified column within the current data table of a dataset. It processes only those rows that are flagged as "of interest" (i.e., have a non-zero acceptance flag). The extracted data is returned as a newly allocated array of float values.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which data is to be retrieved.

Returns

• Pointer to an array of float containing the data from the specified column for all rows marked as "of interest".
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, non-numeric column type, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks.
• This function assumes that the specified column contains numerical data. Attempting to retrieve data from a non-numeric column (excluding SDDS_CHARACTER) will result in an error.

Note

• The number of elements in the returned array corresponds to the number of rows marked as "of interest", which can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.

See also

• SDDS_GetColumnInLongDoubles
• SDDS_GetColumnInDoubles
• SDDS_GetColumn
• SDDS_CountRowsOfInterest

Definition at line 1014 of file SDDS_extract.c.

                                                                             {
  int32_t size, type, index;
  int64_t i, j, n_rows;
  float *data;
  void *rawData;
 
  j = 0;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnInFloats"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetColumnInFloats)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetColumnInFloats)");
    return (NULL);
  }
  if ((type = SDDS_GetColumnType(SDDS_dataset, index)) <= 0 || (size = SDDS_GetTypeSize(type)) <= 0 || (!SDDS_NUMERIC_TYPE(type) && type != SDDS_CHARACTER)) {
    SDDS_SetError("Unable to get column--data size or type undefined or non-numeric (SDDS_GetColumnInFloats)");
    return (NULL);
  }
  if (!(data = (float *)SDDS_Malloc(sizeof(float) * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetColumnInFloats)");
    return (NULL);
  }
  rawData = SDDS_dataset->data[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((long double *)rawData)[i];
    }
    break;
  case SDDS_DOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((double *)rawData)[i];
    }
    break;
  case SDDS_FLOAT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((float *)rawData)[i];
    }
    break;
  case SDDS_LONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int32_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint32_t *)rawData)[i];
    }
    break;
  case SDDS_LONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int64_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint64_t *)rawData)[i];
    }
    break;
  case SDDS_SHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((short *)rawData)[i];
    }
    break;
  case SDDS_USHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((unsigned short *)rawData)[i];
    }
    break;
  case SDDS_CHARACTER:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((char *)rawData)[i];
    }
    break;
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetColumnInFloats)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetColumnInformation()

epicsShareFuncSDDS int32_t SDDS_GetColumnInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Retrieves information about a specified column in the SDDS dataset.

This function is the preferred alternative to SDDS_GetColumnDefinition. It allows you to obtain information about a specific field of a column, either by the column's name or index.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field for which information is requested.
[out]	memory	Pointer to a variable where the retrieved information will be stored. The variable should be of type data_type*, where data_type corresponds to the type of the requested information. For STRING information, use char*. If memory is NULL, the function will verify the existence and type of the information, returning the data type without storing any data.
[in]	mode	Specifies how to identify the column. Valid values are: SDDS_GET_BY_NAME: Identify the column by its name. Requires an additional argument of type char* (column name). SDDS_GET_BY_INDEX: Identify the column by its index. Requires an additional argument of type int32_t (column index).

Returns

On success, returns the SDDS data type of the requested information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the column name or index based on the mode parameter.

See also

SDDS_GetColumnDefinition

Definition at line 41 of file SDDS_info.c.

                                                                                                                 {
  int32_t field_index, type;
  int32_t column_index;
  COLUMN_DEFINITION *columndef;
  char *column_name;
  va_list argptr;
  int32_t retval;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_GetColumnInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_GET_BY_INDEX) {
    if ((column_index = va_arg(argptr, int32_t)) < 0 || column_index >= SDDS_dataset->layout.n_columns) {
      SDDS_SetError("Invalid column index passed. (SDDS_GetColumnInformation)");
      retval = 0;
    }
  } else {
    if (!(column_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL column name passed. (SDDS_GetColumnInformation)");
      retval = 0;
    }
    if ((column_index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
      SDDS_SetError("Unknown column name given (SDDS_GetColumnInformation)");
      retval = 0;
    }
  }
  columndef = SDDS_dataset->layout.column_definition + column_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_COLUMN_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_ColumnFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_COLUMN_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_GetColumnInformation)");
    return (0);
  }
  type = SDDS_ColumnFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString((char **)memory, *((char **)((char *)columndef + SDDS_ColumnFieldInformation[field_index].offset)))) {
      SDDS_SetError("Unable to copy field data (SDDS_GetColumnInformation)");
      return (0);
    }
  } else
    memcpy(memory, (char *)columndef + SDDS_ColumnFieldInformation[field_index].offset, SDDS_type_size[type - 1]);
  return (type);
}

SDDS_GetColumnInLong()

epicsShareFuncSDDS int32_t * SDDS_GetColumnInLong ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves the data of a specified numerical column as an array of 32-bit integers, considering only rows marked as "of interest".

This function extracts data from a specified column within the current data table of a dataset. It processes only those rows that are flagged as "of interest" (i.e., have a non-zero acceptance flag). The extracted data is returned as a newly allocated array of int32_t values.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which data is to be retrieved.

Returns

• Pointer to an array of int32_t containing the data from the specified column for all rows marked as "of interest".
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, non-numeric column type, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks.
• This function assumes that the specified column contains numerical data. Attempting to retrieve data from a non-numeric column (excluding SDDS_CHARACTER) will result in an error.

Note

• The number of elements in the returned array corresponds to the number of rows marked as "of interest", which can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.

See also

• SDDS_GetColumnInLongDoubles
• SDDS_GetColumnInDoubles
• SDDS_GetColumnInFloats
• SDDS_GetColumn
• SDDS_CountRowsOfInterest

Definition at line 1157 of file SDDS_extract.c.

                                                                             {
  int32_t size, type, index;
  int64_t i, j, n_rows;
  int32_t *data;
  void *rawData;
  j = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnInLong"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetColumnInLong)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetColumnInLong)");
    return (NULL);
  }
  if ((type = SDDS_GetColumnType(SDDS_dataset, index)) <= 0 || (size = SDDS_GetTypeSize(type)) <= 0 || (!SDDS_NUMERIC_TYPE(type) && type != SDDS_CHARACTER)) {
    SDDS_SetError("Unable to get column--data size or type undefined or non-numeric (SDDS_GetColumnInLong)");
    return (NULL);
  }
  if (!(data = (int32_t *)SDDS_Malloc(sizeof(int32_t) * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetColumnInLong)");
    return (NULL);
  }
  rawData = SDDS_dataset->data[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((long double *)rawData)[i];
    }
    break;
  case SDDS_DOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((double *)rawData)[i];
    }
    break;
  case SDDS_FLOAT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((float *)rawData)[i];
    }
    break;
  case SDDS_LONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int32_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint32_t *)rawData)[i];
    }
    break;
  case SDDS_LONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int64_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint64_t *)rawData)[i];
    }
    break;
  case SDDS_SHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((short *)rawData)[i];
    }
    break;
  case SDDS_USHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((unsigned short *)rawData)[i];
    }
    break;
  case SDDS_CHARACTER:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((char *)rawData)[i];
    }
    break;
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetColumnInLong)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetColumnInShort()

epicsShareFuncSDDS short * SDDS_GetColumnInShort ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves the data of a specified numerical column as an array of short integers, considering only rows marked as "of interest".

This function extracts data from a specified column within the current data table of a dataset. It processes only those rows that are flagged as "of interest" (i.e., have a non-zero acceptance flag). The extracted data is returned as a newly allocated array of short values.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which data is to be retrieved.

Returns

• Pointer to an array of short containing the data from the specified column for all rows marked as "of interest".
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, non-numeric column type, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks.
• This function assumes that the specified column contains numerical data. Attempting to retrieve data from a non-numeric column (excluding SDDS_CHARACTER) will result in an error.

Note

• The number of elements in the returned array corresponds to the number of rows marked as "of interest", which can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.

See also

• SDDS_GetColumnInLongDoubles
• SDDS_GetColumnInDoubles
• SDDS_GetColumnInFloats
• SDDS_GetColumn
• SDDS_CountRowsOfInterest

Definition at line 1298 of file SDDS_extract.c.

                                                                            {
  int32_t size, type, index;
  int64_t i, j, n_rows;
  short *data;
  void *rawData;
  j = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnInShort"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetColumnInShort)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetColumnInShort)");
    return (NULL);
  }
  if ((type = SDDS_GetColumnType(SDDS_dataset, index)) <= 0 || (size = SDDS_GetTypeSize(type)) <= 0 || (!SDDS_NUMERIC_TYPE(type) && type != SDDS_CHARACTER)) {
    SDDS_SetError("Unable to get column--data size or type undefined or non-numeric (SDDS_GetColumnInShort)");
    return (NULL);
  }
  if (!(data = (short *)SDDS_Malloc(sizeof(short) * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetColumnInShort)");
    return (NULL);
  }
  rawData = SDDS_dataset->data[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((long double *)rawData)[i];
    }
    break;
  case SDDS_DOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((double *)rawData)[i];
    }
    break;
  case SDDS_FLOAT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((float *)rawData)[i];
    }
    break;
  case SDDS_LONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int32_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint32_t *)rawData)[i];
    }
    break;
  case SDDS_LONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((int64_t *)rawData)[i];
    }
    break;
  case SDDS_ULONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((uint64_t *)rawData)[i];
    }
    break;
  case SDDS_SHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((short *)rawData)[i];
    }
    break;
  case SDDS_USHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((unsigned short *)rawData)[i];
    }
    break;
  case SDDS_CHARACTER:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i])
        data[j++] = ((char *)rawData)[i];
    }
    break;
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetColumnInShort)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetColumnInString()

epicsShareFuncSDDS char ** SDDS_GetColumnInString ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves the data of a specified column as an array of strings, considering only rows marked as "of interest".

This function extracts data from a specified column within the current data table of a dataset. It processes only those rows that are flagged as "of interest" (i.e., have a non-zero acceptance flag). The extracted data is returned as a newly allocated array of char* (strings).

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which data is to be retrieved.

Returns

• Pointer to an array of char* containing the data from the specified column for all rows marked as "of interest".
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, non-string column type, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks. Each string within the array should be freed individually, followed by the array itself.
• This function assumes that the specified column contains string data (SDDS_STRING or SDDS_CHARACTER). Attempting to retrieve data from a non-string column will result in an error.

Note

• The number of elements in the returned array corresponds to the number of rows marked as "of interest", which can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.

See also

• SDDS_GetColumnInLongDoubles
• SDDS_GetColumnInDoubles
• SDDS_GetColumnInFloats
• SDDS_GetColumn
• SDDS_CountRowsOfInterest

Definition at line 1439 of file SDDS_extract.c.

                                                                             {
  int32_t size, type, index;
  int64_t i, j, n_rows;
  char **data;
  char buffer[SDDS_MAXLINE];
 
  void *rawData;
  j = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnInString"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetColumnInString)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetColumnInString)");
    return (NULL);
  }
 
  if ((type = SDDS_GetColumnType(SDDS_dataset, index)) <= 0 || (size = SDDS_GetTypeSize(type)) <= 0 ||
      (!SDDS_NUMERIC_TYPE(type) && type != SDDS_CHARACTER && type != SDDS_STRING)) {
    SDDS_SetError("Unable to get column--data size or type undefined or non-numeric (SDDS_GetColumnInString)");
    return (NULL);
  }
  if (!(data = (char **)SDDS_Malloc(sizeof(*data) * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetColumnInString)");
    return (NULL);
  }
  rawData = SDDS_dataset->data[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        if (LDBL_DIG == 18) {
          sprintf(buffer, "%22.18Le", ((long double *)rawData)[i]);
        } else {
          sprintf(buffer, "%22.15Le", ((long double *)rawData)[i]);
        }
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_DOUBLE:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%22.15le", ((double *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_FLOAT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%15.8e", ((float *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_LONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%" PRId64, ((int64_t *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_ULONG64:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%" PRIu64, ((uint64_t *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_LONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%" PRId32, ((int32_t *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_ULONG:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%" PRIu32, ((uint32_t *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_SHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%hd", ((short *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_USHORT:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%hu", ((unsigned short *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_CHARACTER:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        sprintf(buffer, "%c", ((char *)rawData)[i]);
        SDDS_CopyString(&data[j++], buffer);
      }
    }
    break;
  case SDDS_STRING:
    for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
      if (SDDS_dataset->row_flag[i]) {
        SDDS_CopyString(&data[j++], ((char **)rawData)[i]);
      }
    }
    break;
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetColumnInString)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetColumnMemoryMode()

epicsShareFuncSDDS int32_t SDDS_GetColumnMemoryMode ( SDDS_DATASET * SDDS_dataset )

extern

Retrieves the current column memory mode for the SDDS dataset.

Parameters

SDDS_dataset

The SDDS dataset to query.

Returns

The current column memory mode.

Definition at line 1381 of file SDDS_input.c.

                                                             {
  return (SDDS_dataset->layout.data_mode.column_memory_mode);
}

SDDS_GetColumnNames()

epicsShareFuncSDDS char ** SDDS_GetColumnNames ( SDDS_DATASET * SDDS_dataset, int32_t * number )

extern

Retrieves the names of all columns in the SDDS dataset.

This function allocates and returns an array of NULL-terminated strings containing the names of the columns in the provided SDDS_dataset. It only includes columns that are flagged as of interest if column_flag is set.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[out]	number	Pointer to an int32_t variable where the number of retrieved column names will be stored.

Returns

• Returns a pointer to an array of NULL-terminated strings containing the column names on success.
• Returns NULL on failure (e.g., if the dataset is invalid or memory allocation fails) and records an error message.

Note

The caller is responsible for freeing the memory allocated for the returned array and its strings using SDDS_FreeStringArray or similar functions.

See also

SDDS_CheckDataset

SDDS_Malloc

SDDS_CopyString

SDDS_SetError

Definition at line 2526 of file SDDS_utils.c.

                                                                        {
  int64_t i;
  char **name;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnNames"))
    return (NULL);
  *number = 0;
  if (!(name = (char **)SDDS_Malloc(sizeof(*name) * SDDS_dataset->layout.n_columns))) {
    SDDS_SetError("Unable to get column names--allocation failure (SDDS_GetColumnNames)");
    return (NULL);
  }
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++) {
    if (!SDDS_dataset->column_flag || SDDS_dataset->column_flag[i]) {
      if (!SDDS_CopyString(name + *number, SDDS_dataset->layout.column_definition[i].name)) {
        free(name);
        return (NULL);
      }
      *number += 1;
    }
  }
  return (name);
}

SDDS_GetColumnType()

epicsShareFuncSDDS int32_t SDDS_GetColumnType ( SDDS_DATASET * SDDS_dataset, int32_t index )

extern

Retrieves the data type of a column in the SDDS dataset by its index.

This function returns the SDDS data type of the specified column within the dataset. The data type corresponds to one of the predefined SDDS type constants, such as SDDS_LONGDOUBLE, SDDS_DOUBLE, SDDS_FLOAT, etc.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	index	The zero-based index of the column whose data type is to be retrieved. The index should be obtained from SDDS_DefineColumn or SDDS_GetColumnIndex.

Returns

On success, returns the SDDS data type of the column as an int32_t. On failure (e.g., if the index is out of range or the dataset is invalid), returns 0 and records an error message.

Note

The function does not perform type validation beyond checking the index range. It assumes that the dataset's column definitions are correctly initialized.

See also

SDDS_GetColumnIndex

SDDS_SetError

Definition at line 2219 of file SDDS_utils.c.

                                                                      {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetColumnType"))
    return (0);
  if (index < 0 || index >= SDDS_dataset->layout.n_columns) {
    SDDS_SetError("Unable to get column type--column index is out of range (SDDS_GetColumnType)");
    return (0);
  }
  return (SDDS_dataset->layout.column_definition[index].type);
}

SDDS_GetDescription()

epicsShareFuncSDDS int32_t SDDS_GetDescription ( SDDS_DATASET * SDDS_dataset, char ** text, char ** contents )

extern

Retrieves the text and contents descriptions from an SDDS dataset.

This function extracts the text description and contents description from the specified SDDS dataset. The descriptions are copied into the provided pointers if they are not NULL. This allows users to obtain metadata information about the dataset's content and purpose.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
text	Pointer to a char* variable where the text description will be copied. If NULL, the text description is not retrieved.
contents	Pointer to a char* variable where the contents description will be copied. If NULL, the contents description is not retrieved.

Returns

Returns 1 on successful retrieval of the descriptions. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that the descriptions were successfully retrieved and copied.
0	Indicates that an error occurred (e.g., invalid dataset, memory allocation failure).

Note

• The caller is responsible for freeing the memory allocated for text and contents if they are not NULL.
• Ensure that the dataset is properly initialized before calling this function.

See also

SDDS_SetDescription, SDDS_GetArray, SDDS_GetParameter

Definition at line 4627 of file SDDS_extract.c.

                                                                                      {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetDescription"))
    return (0);
  if (text) {
    *text = NULL;
    if (!SDDS_CopyString(text, SDDS_dataset->layout.description)) {
      SDDS_SetError("Unable to retrieve description data (SDDS_GetDescription)");
      return (0);
    }
  }
  if (contents) {
    *contents = NULL;
    if (!SDDS_CopyString(contents, SDDS_dataset->layout.contents)) {
      SDDS_SetError("Unable to retrieve description data (SDDS_GetDescription)");
      return (0);
    }
  }
 
  return (1);
}

SDDS_GetDoubleMatrixFromColumn()

epicsShareFuncSDDS void * SDDS_GetDoubleMatrixFromColumn ( SDDS_DATASET * SDDS_dataset, char * column_name, int64_t dimension1, int64_t dimension2, int32_t mode )

extern

Extracts a matrix of doubles from a specified column in the current data table of an SDDS dataset.

This function retrieves the data from the specified column as double values and organizes it into a matrix with the given dimensions. The data is arranged in either row-major or column-major order based on the mode parameter. The function allocates memory for the matrix, which should be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
column_name	A null-terminated string specifying the name of the column from which to extract the matrix.
dimension1	The number of rows in the resulting matrix.
dimension2	The number of columns in the resulting matrix.
mode	Specifies the data layout in the matrix. Use SDDS_ROW_MAJOR_DATA for row-major order or SDDS_COLUMN_MAJOR_DATA for column-major order.

Returns

On success, returns a pointer to the allocated matrix containing double values. The matrix is an array of pointers, where each pointer refers to a row (for row-major) or a column (for column-major) in the matrix. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, column not found, dimension mismatch, memory allocation failure).
Non-NULL	Pointer to the allocated matrix containing double values.

Note

The caller is responsible for freeing the allocated matrix and its contents.

See also

SDDS_GetMatrixFromColumn, SDDS_GetDoubleMatrixFromRow, SDDS_AllocateMatrix

Definition at line 3215 of file SDDS_extract.c.

                                                                                                                                          {
  int32_t size, index;
  int64_t n_rows, i, j;
  void **data, *column;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetDoubleMatrixFromColumn"))
    return (NULL);
  if (!column_name) {
    SDDS_SetError("Unable to get matrix--column name is NULL (SDDS_GetDoubleMatrixFromColumn)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get matrix--no rows selected (SDDS_GetDoubleMatrixFromColumn)");
    return (NULL);
  }
  if (n_rows != dimension1 * dimension2) {
    char s[1024];
    sprintf(s, "Unable to get matrix--number of rows (%" PRId64 ") doesn't correspond to given dimensions (%" PRId64 " x %" PRId64 ") (SDDS_GetDoubleMatrixFromColumn)", n_rows, dimension1, dimension2);
    SDDS_SetError(s);
    return (NULL);
  }
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get matrix--column name is unrecognized (SDDS_GetDoubleMatrixFromColumn)");
    return (NULL);
  }
  if (!(column = SDDS_GetColumnInDoubles(SDDS_dataset, column_name))) {
    SDDS_SetError("Unable to get matrix (SDDS_GetDoubleMatrixFromColumn)");
    return (NULL);
  }
  size = sizeof(double);
  if (!(data = SDDS_AllocateMatrix(size, dimension1, dimension2))) {
    SDDS_SetError("Unable to allocate matrix (SDDS_GetDoubleMatrixFromColumn)");
    return (NULL);
  }
  if (mode & SDDS_ROW_MAJOR_DATA || !(mode & SDDS_COLUMN_MAJOR_DATA)) {
    for (i = 0; i < dimension1; i++)
      memcpy(data[i], (char *)column + i * dimension2 * size, dimension2 * size);
  } else {
    for (i = 0; i < dimension1; i++) {
      for (j = 0; j < dimension2; j++) {
        memcpy((char *)data[i] + size * j, (char *)column + (j * dimension1 + i) * size, size);
      }
    }
  }
 
  free(column);
  return (data);
}

SDDS_GetErrorMessages()

epicsShareFuncSDDS char ** SDDS_GetErrorMessages ( int32_t * number, int32_t mode )

extern

Retrieves recorded error messages from the SDDS error stack.

This function fetches error messages that have been recorded by SDDS library routines. Depending on the mode parameter, it can retrieve a single error message or all recorded errors.

Parameters

[out]	number	Pointer to an int32_t variable where the number of retrieved error messages will be stored. If NULL, the function returns NULL.
[in]	mode	Flags controlling the retrieval behavior: 0: Retrieve only the most recent error message. SDDS_ALL_GetErrorMessages: Retrieve all recorded error messages.

Returns

A dynamically allocated array of strings containing the error messages. Returns NULL if no errors are recorded or if memory allocation fails.

Note

The caller is responsible for freeing the memory allocated for the returned error messages.

See also

SDDS_SetError

SDDS_ClearErrors

Definition at line 526 of file SDDS_utils.c.

                                                            {
  int32_t i, j, depth;
  char **message;
 
  if (!number)
    return NULL;
 
  *number = 0;
  if (!n_errors)
    return NULL;
 
  if (mode & SDDS_ALL_GetErrorMessages)
    depth = n_errors;
  else
    depth = 1;
  if (!(message = (char **)SDDS_Malloc(sizeof(*message) * depth)))
    return NULL;
  for (i = 0; i < depth; i++)
    message[i] = NULL;
  if (!error_description) {
    fprintf(stderr, "warning: internal error: error_description pointer is unexpectedly NULL (SDDS_GetErrorMessages)\n");
    free(message);
    return NULL;
  } else {
    for (i = depth - 1; i >= 0; i--) {
      if (!error_description[i]) {
        fprintf(stderr, "internal error: error_description[%" PRId32 "] is unexpectedly NULL (SDDS_GetErrorMessages)\n", i);
        for (j = 0; j < depth; j++)
          free(message[j]);
        free(message);
        return NULL;
      }
      if (!SDDS_CopyString(message + i, error_description[i])) {
        fprintf(stderr, "unable to copy error message text (SDDS_GetErrorMessages)\n");
        for (j = 0; j < depth; j++)
          free(message[j]);
        free(message);
        return NULL;
      }
    }
  }
  *number = depth;
  return message;
}

SDDS_GetFixedValueParameter()

epicsShareFuncSDDS void * SDDS_GetFixedValueParameter ( SDDS_DATASET * SDDS_dataset, char * parameter_name, void * memory )

extern

Retrieves the fixed value of a specified parameter from an SDDS dataset.

This function accesses the fixed value defined for a given parameter in the dataset's layout and converts it to the appropriate data type. If the memory pointer is provided, the converted value is stored at the specified memory location. Otherwise, memory is allocated internally to hold the value, which must be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter whose fixed value is to be retrieved.
memory	Optional pointer to a memory location where the fixed value will be stored. The size of the memory should correspond to the size of the parameter's data type. If NULL, memory is allocated internally to hold the value.

Returns

On success, returns a pointer to the memory containing the fixed value. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, parameter not found, invalid data type, memory allocation failure, or scan failure).
Non-NULL	Pointer to the memory containing the fixed parameter value.

Note

The caller is responsible for freeing the allocated memory if the memory parameter is NULL.

See also

SDDS_SetParameterFixedValue, SDDS_GetParameterAsDouble, SDDS_GetParameterAsString

Definition at line 3085 of file SDDS_extract.c.

                                                                                                  {
  int32_t index, type, size;
  void *data;
  char s[SDDS_MAXLINE];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetFixValueParameter"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetFixedValueParameter)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetFixedValueParameter)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetFixedValueParameter)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if (memory)
    data = memory;
  else if (!(data = SDDS_Malloc(size))) {
    SDDS_SetError("Unable to get parameter value--parameter data size is invalid (SDDS_GetFixedValueParameter)");
    return (NULL);
  }
  strcpy(s, SDDS_dataset->layout.parameter_definition[index].fixed_value);
  if (!SDDS_ScanData(s, type, 0, data, 0, 1)) {
    SDDS_SetError("Unable to retrieve fixed-value paramter--scan failed (SDDS_GetFixedValueParameter)");
    return (NULL);
  }
  return (data);
}

SDDS_GetInternalColumn()

epicsShareFuncSDDS void * SDDS_GetInternalColumn ( SDDS_DATASET * SDDS_dataset, char * column_name )

extern

Retrieves an internal pointer to the data of a specified column, including all rows.

This function returns a direct pointer to the internal data array of the specified column. Unlike SDDS_GetColumn, it includes all rows, regardless of their acceptance flags.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column to retrieve.

Returns

• Pointer to the internal data array on success. The type of the pointer corresponds to the column's data type.
• NULL on failure, with an error message recorded (e.g., unrecognized column name).

Warning

Modifying the data through the returned pointer affects the internal state of the dataset. Use with caution to avoid unintended side effects.

Note

• If the column's memory mode is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data may be freed after access.
• This function does not allocate new memory; it provides direct access to the dataset's internal structures.

See also

SDDS_GetColumn, SDDS_SetColumnFlags, SDDS_CountColumnsOfInterest

Definition at line 688 of file SDDS_extract.c.

                                                                            {
  int32_t index;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetInternalColumn"))
    return (NULL);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetInternalColumn)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
  }
  return SDDS_dataset->data[index];
}

SDDS_GetLZMACompressionLevel()

epicsShareFuncSDDS int32_t SDDS_GetLZMACompressionLevel ( void )

extern

Definition at line 91 of file SDDS_lzma.c.

                                           {
  return SDDS_GetLockedLZMACompressionLevel();
}

SDDS_GetMatrixFromColumn()

epicsShareFuncSDDS void * SDDS_GetMatrixFromColumn ( SDDS_DATASET * SDDS_dataset, char * column_name, int64_t dimension1, int64_t dimension2, int32_t mode )

extern

Extracts a matrix from a specified column in the current data table of an SDDS dataset.

This function retrieves the data from the specified column and organizes it into a matrix with the given dimensions. The data is arranged in either row-major or column-major order based on the mode parameter. The function allocates memory for the matrix, which should be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
column_name	A null-terminated string specifying the name of the column from which to extract the matrix.
dimension1	The number of rows in the resulting matrix.
dimension2	The number of columns in the resulting matrix.
mode	Specifies the data layout in the matrix. Use SDDS_ROW_MAJOR_DATA for row-major order or SDDS_COLUMN_MAJOR_DATA for column-major order.

Returns

On success, returns a pointer to the allocated matrix. The matrix is an array of pointers, where each pointer refers to a row (for row-major) or a column (for column-major) in the matrix. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, column not found, dimension mismatch, memory allocation failure).
Non-NULL	Pointer to the allocated matrix.

Note

The caller is responsible for freeing the allocated matrix and its contents.

See also

SDDS_GetDoubleMatrixFromColumn, SDDS_GetMatrixFromRow, SDDS_AllocateMatrix

Definition at line 3143 of file SDDS_extract.c.

                                                                                                                                    {
  int32_t size, type, index;
  int64_t n_rows, i, j;
  void **data, *column;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetMatrixFromColumn"))
    return (NULL);
  if (!column_name) {
    SDDS_SetError("Unable to get matrix--column name is NULL (SDDS_GetMatrixFromColumn)");
    return (NULL);
  }
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get matrix--no rows selected (SDDS_GetMatrixFromColumn)");
    return (NULL);
  }
  if (n_rows != dimension1 * dimension2) {
    char s[1024];
    sprintf(s, "Unable to get matrix--number of rows (%" PRId64 ") doesn't correspond to given dimensions (%" PRId64 " x %" PRId64 ") (SDDS_GetMatrixFromColumn)", n_rows, dimension1, dimension2);
    SDDS_SetError(s);
    return (NULL);
  }
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0 || (type = SDDS_GetColumnType(SDDS_dataset, index)) < 0 || (size = SDDS_GetTypeSize(type)) <= 0) {
    SDDS_SetError("Unable to get matrix--column name is unrecognized (SDDS_GetMatrixFromColumn)");
    return (NULL);
  }
  if (!(column = SDDS_GetColumn(SDDS_dataset, column_name))) {
    SDDS_SetError("Unable to get matrix (SDDS_GetMatrixFromColumn)");
    return (NULL);
  }
  if (!(data = SDDS_AllocateMatrix(size, dimension1, dimension2))) {
    SDDS_SetError("Unable to allocate matrix (SDDS_GetMatrixFromColumn)");
    return (NULL);
  }
  if (mode & SDDS_ROW_MAJOR_DATA || !(mode & SDDS_COLUMN_MAJOR_DATA)) {
    for (i = 0; i < dimension1; i++)
      memcpy(data[i], (char *)column + i * dimension2 * size, dimension2 * size);
  } else {
    for (i = 0; i < dimension1; i++) {
      for (j = 0; j < dimension2; j++) {
        memcpy((char *)data[i] + size * j, (char *)column + (j * dimension1 + i) * size, size);
      }
    }
  }
 
  free(column);
  return (data);
}

SDDS_GetMatrixOfRows()

epicsShareFuncSDDS void * SDDS_GetMatrixOfRows ( SDDS_DATASET * SDDS_dataset, int64_t * n_rows )

extern

Retrieves all rows marked as "of interest" as a matrix (array of row arrays).

This function extracts all rows that are flagged as "of interest" within the current data table of a dataset. It processes only those columns that are flagged as "of interest" and returns the data as a matrix, where each row is an array of values corresponding to the selected columns.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
n_rows	Pointer to an int64_t variable where the number of rows retrieved will be stored.

Returns

• Pointer to an array of pointers, where each pointer references a row's data array.
• NULL if an error occurs (e.g., invalid dataset, no columns selected, inconsistent row types, memory allocation failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks. This includes freeing each individual row array followed by the array of pointers itself.
• All selected columns must have the same data type. If there is an inconsistency, the function will fail.

Note

• The number of rows retrieved is stored in the variable pointed to by n_rows.
• For columns containing string data (SDDS_STRING), each element in the row arrays is a dynamically allocated string that must be freed individually.
• If the dataset's memory mode for the columns is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the columns may be freed after access.

See also

• SDDS_GetRowType
• SDDS_SetColumnFlags
• SDDS_GetRow
• SDDS_CountRowsOfInterest

Definition at line 2267 of file SDDS_extract.c.

                                                                        {
  void **data;
  int32_t size, type;
  int64_t i, j, k;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetMatrixOfRows"))
    return (NULL);
  if (SDDS_dataset->n_of_interest <= 0) {
    SDDS_SetError("Unable to get matrix of rows--no columns selected (SDDS_GetMatrixOfRows)");
    return (NULL);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_GetMatrixOfRows"))
    return (NULL);
  if ((type = SDDS_GetRowType(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get row--inconsistent data type in selected columns (SDDS_GetMatrixOfRows)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if ((*n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get matrix of rows--no rows of interest (SDDS_GetMatrixOfRows)");
    return (NULL);
  }
  if (!(data = (void **)SDDS_Malloc(sizeof(*data) * (*n_rows)))) {
    SDDS_SetError("Unable to get matrix of rows--memory allocation failure (SDDS_GetMatrixOfRows)");
    return (NULL);
  }
  for (j = k = 0; j < SDDS_dataset->n_rows; j++) {
    if (SDDS_dataset->row_flag[j]) {
      if (!(data[k] = SDDS_Malloc(size * SDDS_dataset->n_of_interest))) {
        SDDS_SetError("Unable to get matrix of rows--memory allocation failure (SDDS_GetMatrixOfRows)");
        return (NULL);
      }
      if (type != SDDS_STRING)
        for (i = 0; i < SDDS_dataset->n_of_interest; i++)
          memcpy((char *)data[k] + i * size, (char *)SDDS_dataset->data[SDDS_dataset->column_order[i]] + j * size, size);
      else
        for (i = 0; i < SDDS_dataset->n_of_interest; i++)
          if (!SDDS_CopyString((char **)(data[k]) + i, ((char **)SDDS_dataset->data[SDDS_dataset->column_order[i]])[j]))
            return (NULL);
      k++;
    }
  }
  return (data);
}

SDDS_GetNamedArrayType()

epicsShareFuncSDDS int32_t SDDS_GetNamedArrayType ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the data type of an array in the SDDS dataset by its name.

This function searches for an array by its name within the dataset and returns its SDDS data type. The data type corresponds to one of the predefined SDDS type constants, such as SDDS_LONGDOUBLE, SDDS_DOUBLE, SDDS_FLOAT, etc.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the array whose data type is to be retrieved.

Returns

On success, returns the SDDS data type of the array as an int32_t. On failure (e.g., if the array name is not found or the dataset is invalid), returns 0 and records an error message.

Note

The function internally uses SDDS_GetArrayIndex to find the array's index before retrieving its type.

See also

SDDS_GetArrayIndex

SDDS_SetError

Definition at line 2293 of file SDDS_utils.c.

                                                                       {
  int32_t index;
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, name)) < 0 || index >= SDDS_dataset->layout.n_arrays) {
    SDDS_SetError("Unable to get array type--array index is out of range (SDDS_GetNamedArrayType)");
    return (0);
  }
  return (SDDS_dataset->layout.array_definition[index].type);
}

SDDS_GetNamedColumnType()

epicsShareFuncSDDS int32_t SDDS_GetNamedColumnType ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the data type of a column in the SDDS dataset by its name.

This function searches for a column by its name within the dataset and returns its SDDS data type. The data type corresponds to one of the predefined SDDS type constants, such as SDDS_LONGDOUBLE, SDDS_DOUBLE, SDDS_FLOAT, etc.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the column whose data type is to be retrieved.

Returns

On success, returns the SDDS data type of the column as an int32_t. On failure (e.g., if the column name is not found or the dataset is invalid), returns 0 and records an error message.

Note

The function internally uses SDDS_GetColumnIndex to find the column's index before retrieving its type.

See also

SDDS_GetColumnIndex

SDDS_SetError

Definition at line 2244 of file SDDS_utils.c.

                                                                        {
  int64_t index;
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0 || index >= SDDS_dataset->layout.n_columns) {
    SDDS_SetError("Unable to get column type--column index is out of range (SDDS_GetNamedColumnType)");
    return (0);
  }
  return (SDDS_dataset->layout.column_definition[index].type);
}

SDDS_GetNamedParameterType()

epicsShareFuncSDDS int32_t SDDS_GetNamedParameterType ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the data type of a parameter in the SDDS dataset by its name.

This function searches for a parameter by its name within the dataset and returns its SDDS data type. The data type corresponds to one of the predefined SDDS type constants, such as SDDS_LONGDOUBLE, SDDS_DOUBLE, SDDS_FLOAT, etc.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the parameter whose data type is to be retrieved.

Returns

On success, returns the SDDS data type of the parameter as an int32_t. On failure (e.g., if the parameter name is not found or the dataset is invalid), returns 0 and records an error message.

Note

The function internally uses SDDS_GetParameterIndex to find the parameter's index before retrieving its type.

See also

SDDS_GetParameterIndex

SDDS_SetError

Definition at line 2342 of file SDDS_utils.c.

                                                                           {
  int32_t index;
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0 || index >= SDDS_dataset->layout.n_parameters) {
    SDDS_SetError("Unable to get parameter type--parameter index is out of range (SDDS_GetNamedParameterType)");
    return (0);
  }
  return (SDDS_dataset->layout.parameter_definition[index].type);
}

SDDS_GetNumericColumn()

epicsShareFuncSDDS void * SDDS_GetNumericColumn ( SDDS_DATASET * SDDS_dataset, char * column_name, int32_t desiredType )

extern

Retrieves the data of a specified numerical column as an array of a desired numerical type, considering only rows marked as "of interest".

This function extracts data from a specified column within the current data table of a dataset. It processes only those rows that are flagged as "of interest" (i.e., have a non-zero acceptance flag). The extracted data is returned as a newly allocated array of the specified numerical type.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which data is to be retrieved.
desiredType	Integer constant representing the desired data type for the returned array. Must be one of the supported SDDS numerical types (e.g., SDDS_DOUBLE, SDDS_FLOAT, etc.).

Returns

• Pointer to an array of the desired numerical type containing the data from the specified column for all rows marked as "of interest".
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, non-numeric column type, memory allocation failure, type casting failure). In this case, an error message is recorded internally.

Warning

• The caller is responsible for freeing the allocated memory to prevent memory leaks.
• This function assumes that the specified column contains numerical data. Attempting to retrieve data from a non-numeric column (excluding SDDS_CHARACTER) will result in an error.

Note

• The number of elements in the returned array corresponds to the number of rows marked as "of interest", which can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.
• If the desiredType matches the column's data type, this function internally calls SDDS_GetColumn. Otherwise, it performs type casting using SDDS_CastValue.

See also

• SDDS_GetColumnInLongDoubles
• SDDS_GetColumnInDoubles
• SDDS_GetColumnInFloats
• SDDS_GetColumn
• SDDS_CountRowsOfInterest

Definition at line 1618 of file SDDS_extract.c.

                                                                                                {
  int32_t size, type, desiredTypeSize, index;
  int64_t i, j, n_rows;
  void *data;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetNumericColumn"))
    return (NULL);
  if (!SDDS_NUMERIC_TYPE(desiredType) && desiredType != SDDS_CHARACTER) {
    SDDS_SetError("Unable to get column--desired type is nonnumeric (SDDS_GetNumericColumn)");
    return (NULL);
  }
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_GetNumericColumn)");
    return (NULL);
  }
  if ((type = SDDS_GetColumnType(SDDS_dataset, index)) <= 0 || (size = SDDS_GetTypeSize(type)) <= 0 || (!SDDS_NUMERIC_TYPE(type) && type != SDDS_CHARACTER)) {
    SDDS_SetError("Unable to get column--data size or type undefined or non-numeric (SDDS_GetNumericColumn)");
    return (NULL);
  }
  if (type == desiredType)
    return SDDS_GetColumn(SDDS_dataset, column_name);
  if ((n_rows = SDDS_CountRowsOfInterest(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get column--no rows left (SDDS_GetNumericColumn)");
    return (NULL);
  }
  if (!(data = (void *)SDDS_Malloc((desiredTypeSize = SDDS_GetTypeSize(desiredType)) * n_rows))) {
    SDDS_SetError("Unable to get column--memory allocation failure (SDDS_GetNumericColumn)");
    return (NULL);
  }
  for (i = j = 0; i < SDDS_dataset->n_rows; i++) {
    if (SDDS_dataset->row_flag[i] && !SDDS_CastValue(SDDS_dataset->data[index], i, type, desiredType, (char *)data + desiredTypeSize * j++)) {
      SDDS_SetError("Unable to get column--cast to double failed (SDDS_GetNumericColumn)");
      return (NULL);
    }
  }
  if (j != n_rows) {
    SDDS_SetError("Unable to get column--row number mismatch (SDDS_GetNumericColumn)");
    return (NULL);
  }
  if (SDDS_GetColumnMemoryMode(SDDS_dataset) == DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS) {
    SDDS_dataset->column_track_memory[index] = 0;
    //Free internal copy now under the assumption that the program will not ask for it again.
    if (type == SDDS_STRING) {
      if (0) {
        //FIX this. It currently causes a memory error in SDDS_ScanData2 with multipage files
        char **ptr = (char **)SDDS_dataset->data[index];
        for (i = 0; i < SDDS_dataset->n_rows_allocated; i++, ptr++)
          if (*ptr)
            free(*ptr);
        free(SDDS_dataset->data[index]);
        SDDS_dataset->data[index] = NULL;
      }
    } else {
      free(SDDS_dataset->data[index]);
      SDDS_dataset->data[index] = NULL;
    }
  }
  return (data);
}

SDDS_GetParameter()

epicsShareFuncSDDS void * SDDS_GetParameter ( SDDS_DATASET * SDDS_dataset, char * parameter_name, void * memory )

extern

Retrieves the value of a specified parameter from the current data table of a data set.

This function accesses the value of a specific parameter (identified by its name) within the current data table of a dataset. The retrieved value is either copied into user-provided memory or returned as a direct pointer to the internal data.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
parameter_name	NULL-terminated string specifying the name of the parameter from which the value is to be retrieved.
memory	Pointer to user-allocated memory where the retrieved parameter value will be stored. If NULL, the function allocates memory.

Returns

• Pointer to the retrieved parameter value stored in memory (if provided) or to newly allocated memory.
• NULL if an error occurs (e.g., invalid dataset, unrecognized parameter name, undefined data type, memory allocation failure, string copy failure). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function allocates memory that the caller must free to prevent memory leaks.
• For parameters containing string data (SDDS_STRING), the function copies the string into memory. A typical usage would involve passing a pointer to a char* variable. c char *string; SDDS_GetParameter(&SDDS_dataset, "parameter_name", &string); // or string = *(char**)SDDS_GetParameter(&SDDS_dataset, "parameter_name", NULL);

Note

• The size of the allocated memory corresponds to the parameter's data type, which can be obtained using SDDS_GetParameterType.
• If the dataset's memory mode for the parameter is set to DONT_TRACK_PARAMETER_MEMORY_AFTER_ACCESS, the internal data for the parameter may be freed after access.

See also

• SDDS_GetParameters
• SDDS_GetParameterByIndex
• SDDS_SetParameter
• SDDS_GetParameterType

Definition at line 2482 of file SDDS_extract.c.

                                                                                        {
  int32_t index, type, size;
  char s[SDDS_MAXLINE];
  void *data;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameter"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameter)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    sprintf(s, "Unable to get parameter value--parameter name %s is unrecognized (SDDS_GetParameter)", parameter_name);
    SDDS_SetError(s);
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameter)");
    return (NULL);
  }
  if (!SDDS_dataset->parameter || !SDDS_dataset->parameter[index]) {
    SDDS_SetError("Unable to get parameter value--parameter data array is NULL (SDDS_GetParameter)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if (memory)
    data = memory;
  else if (!(data = SDDS_Malloc(size))) {
    SDDS_SetError("Unable to get parameter value--parameter data size is invalid (SDDS_GetParameter)");
    return (NULL);
  }
  if (type != SDDS_STRING)
    memcpy(data, SDDS_dataset->parameter[index], size);
  else if (!SDDS_CopyString((char **)data, *(char **)SDDS_dataset->parameter[index]))
    return (NULL);
  return (data);
}

SDDS_GetParameterAsDouble()

epicsShareFuncSDDS double * SDDS_GetParameterAsDouble ( SDDS_DATASET * SDDS_dataset, char * parameter_name, double * memory )

extern

Retrieves the value of a specified parameter as a double from the current data table of an SDDS dataset.

This function searches for the parameter by name within the provided SDDS dataset and retrieves its value as a double. If the memory pointer is supplied, the value is stored at the specified memory location. If memory is NULL, the function allocates memory for storing the value, which should be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to retrieve.
memory	Optional pointer to a double variable where the parameter value will be stored. If NULL, memory is allocated internally to hold the value.

Returns

On success, returns a pointer to the double containing the parameter value. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, parameter not found, type mismatch, or memory allocation failure).
Non-NULL	Pointer to the double containing the parameter value.

Note

The caller is responsible for freeing the allocated memory if the memory parameter is NULL.

See also

SDDS_GetParameterAsLong64, SDDS_GetParameterAsLongDouble, SDDS_GetParameterAsString

Definition at line 2783 of file SDDS_extract.c.

                                                                                                    {
  int32_t index = -1, type = -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterAsDouble"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameterAsDouble)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetParameterAsDouble)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterAsDouble)");
    return (NULL);
  }
  if (type == SDDS_STRING) {
    SDDS_SetError("Unable to get parameter value--parameter data type is SDDS_STRING (SDDS_GetParameterAsDouble)");
    return (NULL);
  }
  if (!SDDS_dataset->parameter || !SDDS_dataset->parameter[index]) {
    SDDS_SetError("Unable to get parameter value--parameter data array is NULL (SDDS_GetParameterAsDouble)");
    return (NULL);
  }
 
  if (!memory && !(memory = (double *)SDDS_Malloc(sizeof(double)))) {
    SDDS_SetError("Unable to get parameter value--memory allocation failure (SDDS_GetParameterAsDouble)");
    return (NULL);
  }
  *memory = SDDS_ConvertToDouble(type, SDDS_dataset->parameter[index], 0);
  return (memory);
}

SDDS_GetParameterAsFormattedString()

epicsShareFuncSDDS char * SDDS_GetParameterAsFormattedString ( SDDS_DATASET * SDDS_dataset, char * parameter_name, char ** memory, char * suppliedformat )

extern

Retrieves the value of a specified parameter as a formatted string from the current data table of an SDDS dataset.

This function searches for the parameter by name within the provided SDDS dataset, formats its value based on the supplied format string, and returns it as a null-terminated string. If suppliedformat is NULL, the function uses the format string defined in the parameter's definition. If the memory pointer is provided, the formatted string is stored at the specified memory location. Otherwise, memory is allocated internally to hold the string, which must be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to retrieve.
memory	Optional pointer to a char* variable where the formatted string will be stored. If NULL, memory is allocated internally to hold the string.
suppliedformat	A null-terminated format string (similar to printf format specifiers) to format the parameter value. If NULL, the function uses the format string defined in the parameter's definition within the dataset.

Returns

On success, returns a pointer to the null-terminated formatted string containing the parameter value. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, parameter not found, invalid format string, type mismatch, memory allocation failure, or unknown data type).
Non-NULL	Pointer to the null-terminated string containing the formatted parameter value.

Note

The caller is responsible for freeing the allocated memory if the memory parameter is NULL.

See also

SDDS_GetParameterAsDouble, SDDS_GetParameterAsString, SDDS_GetParameterAsLong64, SDDS_GetParameterAsLongDouble

Definition at line 2936 of file SDDS_extract.c.

                                                                                                                                {
  int32_t index, type;
  char buffer[SDDS_MAXLINE], *parValue;
  void *value;
  char *format = NULL;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterAsFormattedString"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameterAsFormattedString)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetParameterAsFormattedString)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterAsFormattedString)");
    return (NULL);
  }
  if (suppliedformat != NULL) {
    format = suppliedformat;
    if (!SDDS_VerifyPrintfFormat(format, type)) {
      SDDS_SetError("Unable to get parameter value--given format for parameter is invalid (SDDS_GetParameterAsFormattedString)");
      return (NULL);
    }
  } else {
    if (SDDS_GetParameterInformation(SDDS_dataset, "format_string", &format, SDDS_GET_BY_INDEX, index) != SDDS_STRING) {
      SDDS_SetError("Unable to get parameter value--parameter definition is invalid (SDDS_GetParameterAsFormattedString)");
      return (NULL);
    }
  }
  value = SDDS_dataset->parameter[index];
 
  if (!SDDS_StringIsBlank(format)) {
    switch (type) {
    case SDDS_LONGDOUBLE:
      sprintf(buffer, format, *(long double *)value);
      break;
    case SDDS_DOUBLE:
      sprintf(buffer, format, *(double *)value);
      break;
    case SDDS_FLOAT:
      sprintf(buffer, format, *(float *)value);
      break;
    case SDDS_LONG64:
      sprintf(buffer, format, *(int64_t *)value);
      break;
    case SDDS_ULONG64:
      sprintf(buffer, format, *(uint64_t *)value);
      break;
    case SDDS_LONG:
      sprintf(buffer, format, *(int32_t *)value);
      break;
    case SDDS_ULONG:
      sprintf(buffer, format, *(uint32_t *)value);
      break;
    case SDDS_SHORT:
      sprintf(buffer, format, *(short *)value);
      break;
    case SDDS_USHORT:
      sprintf(buffer, format, *(unsigned short *)value);
      break;
    case SDDS_CHARACTER:
      sprintf(buffer, format, *(char *)value);
      break;
    case SDDS_STRING:
      sprintf(buffer, format, *(char **)value);
      break;
    default:
      SDDS_SetError("Unknown data type of parameter (SDDS_GetParameterAsFormattedString)");
      return (NULL);
    }
  } else {
    switch (type) {
    case SDDS_LONGDOUBLE:
      if (LDBL_DIG == 18) {
        sprintf(buffer, "%22.18Le", *(long double *)value);
      } else {
        sprintf(buffer, "%22.15Le", *(long double *)value);
      }
      break;
    case SDDS_DOUBLE:
      sprintf(buffer, "%22.15le", *(double *)value);
      break;
    case SDDS_FLOAT:
      sprintf(buffer, "%15.8e", *(float *)value);
      break;
    case SDDS_LONG64:
      sprintf(buffer, "%" PRId64, *(int64_t *)value);
      break;
    case SDDS_ULONG64:
      sprintf(buffer, "%" PRIu64, *(uint64_t *)value);
      break;
    case SDDS_LONG:
      sprintf(buffer, "%" PRId32, *(int32_t *)value);
      break;
    case SDDS_ULONG:
      sprintf(buffer, "%" PRIu32, *(uint32_t *)value);
      break;
    case SDDS_SHORT:
      sprintf(buffer, "%hd", *(short *)value);
      break;
    case SDDS_USHORT:
      sprintf(buffer, "%hu", *(unsigned short *)value);
      break;
    case SDDS_CHARACTER:
      sprintf(buffer, "%c", *(char *)value);
      break;
    case SDDS_STRING:
      sprintf(buffer, "%s", *(char **)value);
      break;
    default:
      SDDS_SetError("Unknown data type of parameter (SDDS_GetParameterAsFormattedString)");
      return (NULL);
    }
  }
  if (!(parValue = malloc(sizeof(char) * (strlen(buffer) + 1)))) {
    SDDS_SetError("Unable to get parameter value--memory allocation failure (SDDS_GetParameterAsFormattedString)");
    return (NULL);
  }
  strcpy(parValue, buffer);
  if (memory)
    *memory = parValue;
  return parValue;
}

SDDS_GetParameterAsLong()

epicsShareFuncSDDS int32_t * SDDS_GetParameterAsLong ( SDDS_DATASET * SDDS_dataset, char * parameter_name, int32_t * memory )

extern

Retrieves the value of a specified parameter as a 32-bit integer from the current data table of a data set.

This function accesses the value of a specific parameter (identified by its name) within the current data table of a dataset and converts it to a 32-bit integer (int32_t). The converted value is either stored in user-provided memory or allocated by the function.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
parameter_name	NULL-terminated string specifying the name of the parameter from which the value is to be retrieved.
memory	Pointer to a 32-bit integer where the converted parameter value will be stored. If NULL, the function allocates memory.

Returns

• Pointer to the int32_t value stored in memory (if provided) or to newly allocated memory containing the converted value.
• NULL if an error occurs (e.g., invalid dataset, unrecognized parameter name, undefined data type, memory allocation failure, parameter type is SDDS_STRING). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function allocates memory that the caller must free to prevent memory leaks.
• This function does not support parameters of type SDDS_STRING. Attempting to retrieve string parameters as long integers will result in an error.

Note

• The conversion is performed using SDDS_ConvertToLong, which handles casting from various numerical types to int32_t.
• Ensure that the parameter's data type is compatible with 32-bit integer conversion to avoid data loss or undefined behavior.

See also

• SDDS_GetParameter
• SDDS_GetParameterByIndex
• SDDS_ConvertToLong
• SDDS_GetParameterType

Definition at line 2616 of file SDDS_extract.c.

                                                                                                    {
  int32_t index, type;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterAsLong"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameterAsLong)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetParameterAsLong)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterAsLong)");
    return (NULL);
  }
  if (type == SDDS_STRING) {
    SDDS_SetError("Unable to get parameter value--parameter data type is SDDS_STRING (SDDS_GetParameterAsLong)");
    return (NULL);
  }
  if (!SDDS_dataset->parameter || !SDDS_dataset->parameter[index]) {
    SDDS_SetError("Unable to get parameter value--parameter data array is NULL (SDDS_GetParameterAsLong)");
    return (NULL);
  }
 
  if (!memory && !(memory = (int32_t *)SDDS_Malloc(sizeof(int32_t)))) {
    SDDS_SetError("Unable to get parameter value--memory allocation failure (SDDS_GetParameterAsLong)");
    return (NULL);
  }
 
  *memory = SDDS_ConvertToLong(type, SDDS_dataset->parameter[index], 0);
  return (memory);
}

SDDS_GetParameterAsLong64()

epicsShareFuncSDDS int64_t * SDDS_GetParameterAsLong64 ( SDDS_DATASET * SDDS_dataset, char * parameter_name, int64_t * memory )

extern

Retrieves the value of a specified parameter as a 64-bit integer from the current data table of an SDDS dataset.

This function looks up the parameter by name within the given SDDS dataset and returns its value as an int64_t. If the memory pointer is provided, the value is stored at the given memory location. Otherwise, the function allocates memory to store the value, which must be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to retrieve.
memory	Optional pointer to an int64_t variable where the parameter value will be stored. If NULL, memory is allocated internally to hold the value.

Returns

On success, returns a pointer to the int64_t containing the parameter value. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, parameter not found, type mismatch, or memory allocation failure).
Non-NULL	Pointer to the int64_t containing the parameter value.

Note

The caller is responsible for freeing the allocated memory if the memory parameter is NULL.

See also

SDDS_GetParameterAsDouble, SDDS_GetParameterAsString

Definition at line 2672 of file SDDS_extract.c.

                                                                                                      {
  int32_t index, type;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterAsLong64"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameterAsLong64)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetParameterAsLong64)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterAsLong64)");
    return (NULL);
  }
  if (type == SDDS_STRING) {
    SDDS_SetError("Unable to get parameter value--parameter data type is SDDS_STRING (SDDS_GetParameterAsLong64)");
    return (NULL);
  }
  if (!SDDS_dataset->parameter || !SDDS_dataset->parameter[index]) {
    SDDS_SetError("Unable to get parameter value--parameter data array is NULL (SDDS_GetParameterAsLong64)");
    return (NULL);
  }
 
  if (!memory && !(memory = (int64_t *)SDDS_Malloc(sizeof(int64_t)))) {
    SDDS_SetError("Unable to get parameter value--memory allocation failure (SDDS_GetParameterAsLong64)");
    return (NULL);
  }
 
  *memory = SDDS_ConvertToLong64(type, SDDS_dataset->parameter[index], 0);
  return (memory);
}

SDDS_GetParameterAsLongDouble()

epicsShareFuncSDDS long double * SDDS_GetParameterAsLongDouble ( SDDS_DATASET * SDDS_dataset, char * parameter_name, long double * memory )

extern

Retrieves the value of a specified parameter as a long double from the current data table of an SDDS dataset.

This function searches for the parameter by name within the provided SDDS dataset and retrieves its value as a long double. If the memory pointer is supplied, the value is stored at the specified memory location. If memory is NULL, the function allocates memory for storing the value, which should be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to retrieve.
memory	Optional pointer to a long double variable where the parameter value will be stored. If NULL, memory is allocated internally to hold the value.

Returns

On success, returns a pointer to the long double containing the parameter value. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, parameter not found, type mismatch, or memory allocation failure).
Non-NULL	Pointer to the long double containing the parameter value.

Note

The caller is responsible for freeing the allocated memory if the memory parameter is NULL.

See also

SDDS_GetParameterAsDouble, SDDS_GetParameterAsLong64, SDDS_GetParameterAsString

Definition at line 2728 of file SDDS_extract.c.

                                                                                                                  {
  int32_t index = -1, type = -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterAsLongDouble"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameterAsLongDouble)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetParameterAsLongDouble)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterAsLongDouble)");
    return (NULL);
  }
  if (type == SDDS_STRING) {
    SDDS_SetError("Unable to get parameter value--parameter data type is SDDS_STRING (SDDS_GetParameterAsLongDouble)");
    return (NULL);
  }
  if (!SDDS_dataset->parameter || !SDDS_dataset->parameter[index]) {
    SDDS_SetError("Unable to get parameter value--parameter data array is NULL (SDDS_GetParameterAsLongDouble)");
    return (NULL);
  }
 
  if (!memory && !(memory = (long double *)SDDS_Malloc(sizeof(long double)))) {
    SDDS_SetError("Unable to get parameter value--memory allocation failure (SDDS_GetParameterAsLongDouble)");
    return (NULL);
  }
  *memory = SDDS_ConvertToLongDouble(type, SDDS_dataset->parameter[index], 0);
  return (memory);
}

SDDS_GetParameterAsString()

epicsShareFuncSDDS char * SDDS_GetParameterAsString ( SDDS_DATASET * SDDS_dataset, char * parameter_name, char ** memory )

extern

Retrieves the value of a specified parameter as a string from the current data table of an SDDS dataset.

This function searches for the parameter by name within the provided SDDS dataset and retrieves its value as a string. The function formats the parameter's value based on its data type. If the memory pointer is provided, the string is stored at the specified memory location. Otherwise, the function allocates memory to hold the string, which must be freed by the caller.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to retrieve.
memory	Optional pointer to a char* variable where the string will be stored. If NULL, memory is allocated internally to hold the string.

Returns

On success, returns a pointer to the null-terminated string containing the parameter value. On failure, returns NULL and sets an appropriate error message.

Return values

NULL	Indicates that an error occurred (e.g., invalid dataset, parameter not found, type mismatch, memory allocation failure, or unknown data type).
Non-NULL	Pointer to the null-terminated string containing the parameter value.

Note

The caller is responsible for freeing the allocated memory if the memory parameter is NULL.

See also

SDDS_GetParameterAsDouble, SDDS_GetParameterAsLong64, SDDS_GetParameterAsLongDouble

Definition at line 2839 of file SDDS_extract.c.

                                                                                                 {
  int32_t index, type;
  char buffer[SDDS_MAXLINE], *parValue;
  void *value;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterAsString"))
    return (NULL);
  if (!parameter_name) {
    SDDS_SetError("Unable to get parameter value--parameter name pointer is NULL (SDDS_GetParameterAsString)");
    return (NULL);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter value--parameter name is unrecognized (SDDS_GetParameterAsString)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterAsString)");
    return (NULL);
  }
  value = SDDS_dataset->parameter[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    if (LDBL_DIG == 18) {
      sprintf(buffer, "%.18Le", *(long double *)value);
    } else {
      sprintf(buffer, "%.15Le", *(long double *)value);
    }
    break;
  case SDDS_DOUBLE:
    sprintf(buffer, "%.15le", *(double *)value);
    break;
  case SDDS_FLOAT:
    sprintf(buffer, "%.8e", *(float *)value);
    break;
  case SDDS_LONG64:
    sprintf(buffer, "%" PRId64, *(int64_t *)value);
    break;
  case SDDS_ULONG64:
    sprintf(buffer, "%" PRIu64, *(uint64_t *)value);
    break;
  case SDDS_LONG:
    sprintf(buffer, "%" PRId32, *(int32_t *)value);
    break;
  case SDDS_ULONG:
    sprintf(buffer, "%" PRIu32, *(uint32_t *)value);
    break;
  case SDDS_SHORT:
    sprintf(buffer, "%hd", *(short *)value);
    break;
  case SDDS_USHORT:
    sprintf(buffer, "%hu", *(unsigned short *)value);
    break;
  case SDDS_CHARACTER:
    sprintf(buffer, "%c", *(char *)value);
    break;
  case SDDS_STRING:
    sprintf(buffer, "%s", *(char **)value);
    break;
  default:
    SDDS_SetError("Unknown data type of parameter (SDDS_GetParameterAsString)");
    return (NULL);
  }
  if (!(parValue = malloc(sizeof(char) * (strlen(buffer) + 1)))) {
    SDDS_SetError("Unable to get parameter value--memory allocation failure (SDDS_GetParameterAsString)");
    return (NULL);
  }
  strcpy(parValue, buffer);
  if (memory)
    *memory = parValue;
  return parValue;
}

SDDS_GetParameterByIndex()

epicsShareFuncSDDS void * SDDS_GetParameterByIndex ( SDDS_DATASET * SDDS_dataset, int32_t index, void * memory )

extern

Retrieves the value of a specified parameter by its index from the current data table of a data set.

This function accesses the value of a specific parameter (identified by its index) within the current data table of a dataset. The retrieved value is either copied into user-provided memory or returned as a direct pointer to the internal data.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
index	Zero-based index of the parameter to retrieve. Must be within the range [0, n_parameters-1].
memory	Pointer to user-allocated memory where the retrieved parameter value will be stored. If NULL, the function allocates memory.

Returns

• Pointer to the retrieved parameter value stored in memory (if provided) or to newly allocated memory.
• NULL if an error occurs (e.g., invalid dataset, parameter index out of range, undefined data type, memory allocation failure, string copy failure). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function allocates memory that the caller must free to prevent memory leaks.
• For parameters containing string data (SDDS_STRING), the function copies the string into memory. A typical usage would involve passing a pointer to a char* variable. c char *string; SDDS_GetParameterByIndex(&SDDS_dataset, index, &string); // or string = *(char**)SDDS_GetParameterByIndex(&SDDS_dataset, index, NULL);

Note

• The size of the allocated memory corresponds to the parameter's data type, which can be obtained using SDDS_GetParameterType.
• If the dataset's memory mode for the parameter is set to DONT_TRACK_PARAMETER_MEMORY_AFTER_ACCESS, the internal data for the parameter may be freed after access.

See also

• SDDS_GetParameters
• SDDS_GetParameter
• SDDS_SetParameter
• SDDS_GetParameterType

Definition at line 2555 of file SDDS_extract.c.

                                                                                        {
  int32_t type, size;
  void *data;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameter"))
    return (NULL);
  if (index < 0 || index >= SDDS_dataset->layout.n_parameters) {
    SDDS_SetError("Unable to get parameter value--parameter index is invalid (SDDS_GetParameterByIndex)");
    return (NULL);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter value--parameter data type is invalid (SDDS_GetParameterByIndex)");
    return (NULL);
  }
  if (!SDDS_dataset->parameter || !SDDS_dataset->parameter[index]) {
    SDDS_SetError("Unable to get parameter value--parameter data array is NULL (SDDS_GetParameterByIndex)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if (memory)
    data = memory;
  else if (!(data = SDDS_Malloc(size))) {
    SDDS_SetError("Unable to get parameter value--parameter data size is invalid (SDDS_GetParameterByIndex)");
    return (NULL);
  }
  if (type != SDDS_STRING)
    memcpy(data, SDDS_dataset->parameter[index], size);
  else if (!SDDS_CopyString((char **)data, *(char **)SDDS_dataset->parameter[index]))
    return (NULL);
  return (data);
}

SDDS_GetParameterDefinition()

epicsShareFuncSDDS PARAMETER_DEFINITION * SDDS_GetParameterDefinition ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the definition of a specified parameter from the SDDS dataset.

This function searches for a parameter by its name within the provided SDDS dataset. If found, it creates a copy of the parameter's definition and returns a pointer to it. The returned pointer should be freed by the caller using SDDS_FreeParameterDefinition to avoid memory leaks.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the parameter to retrieve.

Returns

On success, returns a pointer to a newly allocated PARAMETER_DEFINITION structure containing the parameter's information. On failure (e.g., if the parameter is not found or a copy fails), returns NULL and records an error message.

Note

The caller is responsible for freeing the returned PARAMETER_DEFINITION pointer using SDDS_FreeParameterDefinition.

See also

SDDS_CopyParameterDefinition

SDDS_FreeParameterDefinition

SDDS_SetError

Definition at line 1141 of file SDDS_utils.c.

                                                                                          {
  int32_t i;
  PARAMETER_DEFINITION *pardef;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterDefinition"))
    return (NULL);
  if (!name) {
    SDDS_SetError("Unable to get parameter definition--name is NULL (SDDS_GetParameterDefinition)");
    return (NULL);
  }
  if ((i = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0)
    return NULL;
  if (!SDDS_CopyParameterDefinition(&pardef, SDDS_dataset->layout.parameter_definition + i)) {
    SDDS_SetError("Unable to get parameter definition--copy failure  (SDDS_GetParameterDefinition)");
    return (NULL);
  }
  return (pardef);
}

SDDS_GetParameterIndex()

epicsShareFuncSDDS int32_t SDDS_GetParameterIndex ( SDDS_DATASET * SDDS_dataset, char * name )

extern

Retrieves the index of a named parameter in the SDDS dataset.

This function searches for a parameter by its name within the provided SDDS dataset and returns its index. The index can then be used with other routines for faster access to the parameter's data or metadata.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	name	A null-terminated string specifying the name of the parameter whose index is desired.

Returns

On success, returns a non-negative integer representing the index of the parameter. On failure (e.g., if the parameter is not found), returns -1 and records an error message.

See also

SDDS_GetParameterDefinition

SDDS_SetError

Definition at line 1404 of file SDDS_utils.c.

                                                                       {
  int32_t i;
  SORTED_INDEX key;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterIndex"))
    return (-1);
  if (!name) {
    SDDS_SetError("Unable to get parameter index--name is NULL (SDDS_GetParameterIndex)");
    return (-1);
  }
  key.name = name;
  if ((i = binaryIndexSearch((void **)SDDS_dataset->layout.parameter_index, SDDS_dataset->layout.n_parameters, &key, SDDS_CompareIndexedNames, 0)) < 0)
    return -1;
  return SDDS_dataset->layout.parameter_index[i]->index;
}

SDDS_GetParameterInformation()

epicsShareFuncSDDS int32_t SDDS_GetParameterInformation ( SDDS_DATASET * SDDS_dataset, char * field_name, void * memory, int32_t mode, ... )

extern

Retrieves information about a specified parameter in the SDDS dataset.

This function is the preferred alternative to SDDS_GetParameterDefinition. It allows you to obtain information about a specific field of a parameter, either by the parameter's name or index.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	field_name	A null-terminated string specifying the name of the field for which information is requested.
[out]	memory	Pointer to a variable where the retrieved information will be stored. The variable should be of type data_type*, where data_type corresponds to the type of the requested information. For STRING information, use char*. If memory is NULL, the function will verify the existence and type of the information, returning the data type without storing any data.
[in]	mode	Specifies how to identify the parameter. Valid values are: SDDS_GET_BY_NAME: Identify the parameter by its name. Requires an additional argument of type char* (parameter name). SDDS_GET_BY_INDEX: Identify the parameter by its index. Requires an additional argument of type int32_t (parameter index).

Returns

On success, returns the SDDS data type of the requested information. On failure, returns zero and records an error message.

Note

This function uses variable arguments to accept either the parameter name or index based on the mode parameter.

See also

SDDS_GetParameterDefinition

Definition at line 117 of file SDDS_info.c.

                                                                                                                    {
  int32_t field_index, type, parameter_index;
  PARAMETER_DEFINITION *parameterdef;
  char *parameter_name;
  va_list argptr;
  int32_t retval;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterInformation"))
    return (0);
 
  if (!field_name) {
    SDDS_SetError("NULL field name passed. (SDDS_GetParameterInformation)");
    return (0);
  }
 
  va_start(argptr, mode);
  retval = 1;
  if (mode & SDDS_GET_BY_INDEX) {
    if ((parameter_index = va_arg(argptr, int32_t)) < 0 || parameter_index >= SDDS_dataset->layout.n_parameters) {
      SDDS_SetError("Invalid parameter index passed. (SDDS_GetParameterInformation)");
      retval = 0;
    }
  } else {
    if (!(parameter_name = va_arg(argptr, char *))) {
      SDDS_SetError("NULL parameter name passed. (SDDS_GetParameterInformation)");
      retval = 0;
    }
    if ((parameter_index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
      SDDS_SetError("Unknown parameter name given (SDDS_GetParameterInformation)");
      retval = 0;
    }
  }
  parameterdef = SDDS_dataset->layout.parameter_definition + parameter_index;
  va_end(argptr);
  if (!retval)
    return (0);
 
  for (field_index = 0; field_index < SDDS_PARAMETER_FIELDS; field_index++)
    if (strcmp(field_name, SDDS_ParameterFieldInformation[field_index].name) == 0)
      break;
  if (field_index == SDDS_PARAMETER_FIELDS) {
    SDDS_SetError("Unknown field name given (SDDS_GetParameterInformation)");
    return (0);
  }
  type = SDDS_ParameterFieldInformation[field_index].type;
  if (!memory)
    return (type);
  if (type == SDDS_STRING) {
    if (!SDDS_CopyString((char **)memory, *((char **)((char *)parameterdef + SDDS_ParameterFieldInformation[field_index].offset)))) {
      SDDS_SetError("Unable to copy field data (SDDS_GetParameterInformation)");
      return (0);
    }
  } else
    memcpy(memory, (char *)parameterdef + SDDS_ParameterFieldInformation[field_index].offset, SDDS_type_size[type - 1]);
  return (type);
}

SDDS_GetParameterNames()

epicsShareFuncSDDS char ** SDDS_GetParameterNames ( SDDS_DATASET * SDDS_dataset, int32_t * number )

extern

Retrieves the names of all parameters in the SDDS dataset.

This function allocates and returns an array of NULL-terminated strings containing the names of the parameters in the provided SDDS_dataset.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[out]	number	Pointer to an int32_t variable where the number of retrieved parameter names will be stored.

Returns

• Returns a pointer to an array of NULL-terminated strings containing the parameter names on success.
• Returns NULL on failure (e.g., if the dataset is invalid or memory allocation fails) and records an error message.

Note

The caller is responsible for freeing the memory allocated for the returned array and its strings using SDDS_FreeStringArray or similar functions.

See also

SDDS_CheckDataset

SDDS_Malloc

SDDS_CopyString

SDDS_SetError

Definition at line 2567 of file SDDS_utils.c.

                                                                           {
  int32_t i;
  char **name;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterNames"))
    return (NULL);
  *number = SDDS_dataset->layout.n_parameters;
  if (!(name = (char **)SDDS_Malloc(sizeof(*name) * SDDS_dataset->layout.n_parameters))) {
    SDDS_SetError("Unable to get parameter names--allocation failure (SDDS_GetParameterNames)");
    return (NULL);
  }
  for (i = 0; i < SDDS_dataset->layout.n_parameters; i++) {
    if (!SDDS_CopyString(name + i, SDDS_dataset->layout.parameter_definition[i].name)) {
      free(name);
      return (NULL);
    }
  }
  return (name);
}

SDDS_GetParameters()

epicsShareFuncSDDS int32_t SDDS_GetParameters ( SDDS_DATASET * SDDS_dataset, ... )

extern

Retrieves multiple parameter values from the current data table of a data set.

This variadic function allows the retrieval of multiple parameter values in a single call. Each parameter's name and corresponding memory location are provided as pairs of arguments.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
...	Variable arguments consisting of pairs of: char *parameter_name: NULL-terminated string specifying the name of the parameter. void *memory: Pointer to memory where the parameter's value will be stored. If NULL, the function will fail for that parameter. The argument list should be terminated when parameter_name is NULL.

Returns

• 1 on successful retrieval of all specified parameters.
• 0 if any parameter retrieval fails. An error message is recorded for the first failure encountered.

Warning

• The function expects an even number of arguments (pairs of parameter names and memory pointers). An odd number may result in undefined behavior.
• Ensure that the memory pointers provided are of appropriate types and have sufficient space to hold the parameter values.

Note

• To terminate the argument list, pass a NULL as the parameter name. c SDDS_GetParameters(&SDDS_dataset, "param1", &value1, "param2", &value2, NULL);

See also

• SDDS_GetParameter
• SDDS_GetParameterByIndex

Definition at line 2421 of file SDDS_extract.c.

                                                            {
  va_list argptr;
  char *name;
  void *data;
  int32_t retval;
  char s[SDDS_MAXLINE];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameters"))
    return 0;
  va_start(argptr, SDDS_dataset);
  retval = 1;
  do {
    if (!(name = va_arg(argptr, char *)))
      break;
    if (!(data = va_arg(argptr, void *)))
      retval = 0;
    if (!SDDS_GetParameter(SDDS_dataset, name, data)) {
      sprintf(s, "Unable to get value of parameter %s (SDDS_GetParameters)", name);
      SDDS_SetError(s);
    }
  } while (retval);
  va_end(argptr);
  return retval;
}

SDDS_GetParameterType()

epicsShareFuncSDDS int32_t SDDS_GetParameterType ( SDDS_DATASET * SDDS_dataset, int32_t index )

extern

Retrieves the data type of a parameter in the SDDS dataset by its index.

This function returns the SDDS data type of the specified parameter within the dataset. The data type corresponds to one of the predefined SDDS type constants, such as SDDS_LONGDOUBLE, SDDS_DOUBLE, SDDS_FLOAT, etc.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	index	The zero-based index of the parameter whose data type is to be retrieved. The index should be obtained from SDDS_DefineParameter or SDDS_GetParameterIndex.

Returns

On success, returns the SDDS data type of the parameter as an int32_t. On failure (e.g., if the index is out of range or the dataset is invalid), returns 0 and records an error message.

Note

The function does not perform type validation beyond checking the index range. It assumes that the dataset's parameter definitions are correctly initialized.

See also

SDDS_GetParameterIndex

SDDS_SetError

Definition at line 2317 of file SDDS_utils.c.

                                                                         {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetParameterType"))
    return (0);
  if (index < 0 || index >= SDDS_dataset->layout.n_parameters) {
    SDDS_SetError("Unable to get parameter type--parameter index is out of range (SDDS_GetParameterType)");
    return (0);
  }
  return (SDDS_dataset->layout.parameter_definition[index].type);
}

SDDS_GetRow()

epicsShareFuncSDDS void * SDDS_GetRow ( SDDS_DATASET * SDDS_dataset, int64_t srow_index, void * memory )

extern

Retrieves the data of a specific selected row as an array, considering only columns marked as "of interest".

This function extracts data from a specific selected row (identified by its selected row index among rows marked as "of interest") within the current data table of a dataset. It processes only those columns that are flagged as "of interest" and returns the row's data as a newly allocated array or stores it in user-provided memory.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
srow_index	Zero-based index representing the position of the selected row among all rows marked as "of interest".
memory	Pointer to user-allocated memory where the retrieved row data will be stored. If NULL, the function allocates memory.

Returns

• Pointer to the retrieved row data array stored in memory (if provided) or to newly allocated memory.
• NULL if an error occurs (e.g., invalid dataset, row index out of range, inconsistent row types, memory allocation failure). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function allocates memory that the caller must free to prevent memory leaks.
• All selected columns must have the same data type. If there is an inconsistency, the function will fail.
• For columns containing string data (SDDS_STRING), each element in the returned array is a dynamically allocated string that must be freed individually, followed by the array itself.

Note

• The number of elements in the returned array corresponds to the number of columns marked as "of interest", which can be obtained using SDDS_CountColumnsOfInterest.
• If the dataset's memory mode for the columns is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the columns may be freed after access.

See also

• SDDS_GetRowType
• SDDS_SetColumnFlags
• SDDS_GetValue
• SDDS_CountColumnsOfInterest

Definition at line 2202 of file SDDS_extract.c.

                                                                                {
  void *data;
  int32_t size, type;
  int64_t i, row_index;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetRow"))
    return (NULL);
  if ((row_index = SDDS_GetSelectedRowIndex(SDDS_dataset, srow_index)) < 0) {
    SDDS_SetError("Unable to get row--row index out of range (SDDS_GetRow)");
    return (NULL);
  }
  if (SDDS_dataset->n_of_interest <= 0) {
    SDDS_SetError("Unable to get row--no columns selected (SDDS_GetRow)");
    return (NULL);
  }
  if ((type = SDDS_GetRowType(SDDS_dataset)) <= 0) {
    SDDS_SetError("Unable to get row--inconsistent data type in selected columns (SDDS_GetRow)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if (memory)
    data = memory;
  else if (!(data = SDDS_Malloc(size * SDDS_dataset->n_of_interest))) {
    SDDS_SetError("Unable to get row--memory allocation failure (SDDS_GetRow)");
    return (NULL);
  }
  if (type != SDDS_STRING)
    for (i = 0; i < SDDS_dataset->n_of_interest; i++)
      memcpy((char *)data + i * size, (char *)SDDS_dataset->data[SDDS_dataset->column_order[i]] + row_index * size, size);
  else
    for (i = 0; i < SDDS_dataset->n_of_interest; i++)
      if (!SDDS_CopyString((char **)data + i, ((char **)SDDS_dataset->data[SDDS_dataset->column_order[i]])[row_index]))
        return (NULL);
  return (data);
}

SDDS_GetRowFlag()

epicsShareFuncSDDS int32_t SDDS_GetRowFlag ( SDDS_DATASET * SDDS_dataset, int64_t row )

extern

Retrieves the acceptance flag of a specific row in the current data table.

This function fetches the acceptance flag for a given row. The flag indicates whether the row is "of interest" (non-zero) or rejected (zero).

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
row	Index of the row whose flag is to be retrieved. Must be within the range [0, n_rows-1].

Returns

• Non-negative integer representing the flag value of the specified row.
• -1 if the dataset is invalid or the row index is out of bounds.

See also

SDDS_SetRowFlags, SDDS_GetRowFlags

Definition at line 71 of file SDDS_extract.c.

                                                                 {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetRowFlag"))
    return -1;
  if (row < 0 || row >= SDDS_dataset->n_rows)
    return -1;
  return SDDS_dataset->row_flag[row];
}

SDDS_GetRowFlags()

epicsShareFuncSDDS int32_t SDDS_GetRowFlags ( SDDS_DATASET * SDDS_dataset, int32_t * flag, int64_t rows )

extern

Retrieves the acceptance flags for all rows in the current data table.

This function copies the acceptance flags of each row into a provided array. Each flag indicates whether the corresponding row is "of interest" (non-zero) or rejected (zero).

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
flag	Pointer to an integer array where the row flags will be stored. The array must have at least rows elements.
rows	Number of rows to retrieve flags for. Typically, this should match the total number of rows in the data table.

Returns

• 1 on successful retrieval of all row flags.
• 0 on failure, with an error message recorded (e.g., if row count mismatches).

Note

Ensure that the flag array is adequately allocated to hold the flags for all specified rows.

See also

SDDS_SetRowFlags, SDDS_GetRowFlag

Definition at line 97 of file SDDS_extract.c.

                                                                                  {
  int64_t i;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetRowFlags"))
    return 0;
  if (rows != SDDS_dataset->n_rows) {
    SDDS_SetError("Row count mismatch (SDDS_GetRowFlags)");
    return 0;
  }
  for (i = 0; i < rows; i++)
    flag[i] = SDDS_dataset->row_flag[i];
  return 1;
}

SDDS_GetRowLimit()

epicsShareFuncSDDS int64_t SDDS_GetRowLimit ( )

extern

Retrieves the current row limit for the SDDS dataset.

Returns

The current row limit.

Definition at line 1259 of file SDDS_input.c.

                           {
  return SDDS_GetLockedRowLimit();
}

SDDS_GetToken()

epicsShareFuncSDDS int32_t SDDS_GetToken ( char * s, char * buffer, int32_t buflen )

extern

Extracts the next token from a string, handling quoted substrings and escape characters.

This function parses the input string s to extract the next token, considering quoted substrings and escape characters. If the token is enclosed in double quotes ("), the function ensures that embedded quotes are handled correctly. After extracting the token, the original string s is updated to remove the extracted portion.

Parameters

[in,out]	s	Pointer to the string from which to extract the token. This string will be modified to remove the extracted token.
[out]	buffer	Pointer to a character array where the extracted token will be stored.
[in]	buflen	The maximum number of characters to copy into buffer, including the null terminator.

Returns

On success, returns the length of the extracted token as an int32_t. If no token is found or an error occurs (e.g., buffer overflow), returns -1.

Note

The function assumes that the input string s is null-terminated. The caller must ensure that buffer has sufficient space to hold the extracted token.

See also

SDDS_GetToken2

Definition at line 1806 of file SDDS_utils.c.

                                                             {
  char *ptr0, *ptr1, *escptr, *temp;
 
  /* save the pointer to the head of the string */
  ptr0 = s;
 
  /* skip leading white-space */
  while (isspace(*s))
    s++;
  if (*s == 0)
    return (-1);
  ptr1 = s;
 
  if (*s == '"') {
    /* if quoted string, skip to next quotation mark */
    ptr1 = s + 1; /* beginning of actual token */
    do {
      s++;
      escptr = NULL;
      if (*s == '\\' && *(s + 1) == '\\') {
        /* skip and remember literal \ (indicated by \\ in the string) */
        escptr = s + 1;
        s += 2;
      }
    } while (*s && (*s != '"' || (*(s - 1) == '\\' && (s - 1) != escptr)));
    /* replace trailing quotation mark with a space */
    if (*s == '"')
      *s = ' ';
  } else {
    /* skip to first white-space following token */
    do {
      s++;
      /* imbedded quotation marks are handled here */
      if (*s == '"' && *(s - 1) != '\\') {
        while (*++s && !(*s == '"' && *(s - 1) != '\\'))
          ;
      }
    } while (*s && !isspace(*s));
  }
 
  if ((int32_t)(s - ptr1) >= buflen)
    return (-1);
  strncpy(buffer, ptr1, s - ptr1);
  buffer[s - ptr1] = 0;
 
  /* update the original string to delete the token */
  temp = malloc(sizeof(char) * (strlen(s) + 1));
  strcpy(temp, s);
  strcpy(ptr0, temp);
  free(temp);
 
  /* return the string length */
  return ((int32_t)(s - ptr1));
}

SDDS_GetToken2()

epicsShareFuncSDDS int32_t SDDS_GetToken2 ( char * s, char ** st, int32_t * strlength, char * buffer, int32_t buflen )

extern

Extracts the next token from a string, handling quoted substrings and escape characters, with updated string pointers.

This function parses the input string s to extract the next token, considering quoted substrings and escape characters. If the token is enclosed in double quotes ("), the function ensures that embedded quotes are handled correctly. After extracting the token, the original string s is updated by adjusting the string pointer st and the remaining string length strlength.

Parameters

[in,out]	s	Pointer to the string from which to extract the token. This string will be modified to remove the extracted token.
[in,out]	st	Pointer to the current position in the string s. This will be updated to point to the next character after the extracted token.
[in,out]	strlength	Pointer to an int32_t variable representing the remaining length of the string s. This will be decremented by the length of the extracted token.
[out]	buffer	Pointer to a character array where the extracted token will be stored.
[in]	buflen	The maximum number of characters to copy into buffer, including the null terminator.

Returns

On success, returns the length of the extracted token as an int32_t. If no token is found or an error occurs (e.g., buffer overflow), returns -1.

Note

The caller is responsible for ensuring that buffer has sufficient space to hold the extracted token. Additionally, st and strlength should accurately reflect the current parsing state of the string.

See also

SDDS_GetToken

Definition at line 1878 of file SDDS_utils.c.

                                                                                             {
  char *ptr0, *ptr1, *escptr;
 
  /* save the pointer to the head of the string */
  ptr0 = s;
 
  /* skip leading white-space */
  while (isspace(*s))
    s++;
  if (*s == 0)
    return (-1);
  ptr1 = s;
 
  if (*s == '"') {
    /* if quoted string, skip to next quotation mark */
    ptr1 = s + 1; /* beginning of actual token */
    do {
      s++;
      escptr = NULL;
      if (*s == '\\' && *(s + 1) == '\\') {
        /* skip and remember literal \ (indicated by \\ in the string) */
        escptr = s + 1;
        s += 2;
      }
    } while (*s && (*s != '"' || (*(s - 1) == '\\' && (s - 1) != escptr)));
    /* replace trailing quotation mark with a space */
    if (*s == '"')
      *s = ' ';
  } else {
    /* skip to first white-space following token */
    do {
      s++;
      /* imbedded quotation marks are handled here */
      if (*s == '"' && *(s - 1) != '\\') {
        while (*++s && !(*s == '"' && *(s - 1) != '\\'))
          ;
      }
    } while (*s && !isspace(*s));
  }
 
  if ((int32_t)(s - ptr1) >= buflen)
    return (-1);
  strncpy(buffer, ptr1, s - ptr1);
  buffer[s - ptr1] = 0;
 
  /* update the original string to delete the token */
  *st += s - ptr0;
  *strlength -= s - ptr0;
 
  /* return the string length including whitespace */
  return ((int32_t)(s - ptr1));
}

SDDS_GetTypeName()

epicsShareFuncSDDS char * SDDS_GetTypeName ( int32_t type )

extern

Retrieves the name of a specified SDDS data type as a string.

This function returns a dynamically allocated string containing the name of the specified SDDS data type. The name corresponds to the textual representation of the data type, such as "double", "float", "int32", etc.

Parameters

[in]

type

The SDDS data type for which the name is requested. Must be one of the predefined constants: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING

Returns

On success, returns a pointer to a newly allocated string containing the name of the data type. On failure (e.g., if the type is invalid or memory allocation fails), returns NULL.

Note

The caller is responsible for freeing the memory allocated for the returned string using SDDS_Free.

See also

SDDS_GetTypeSize

SDDS_SetError

Definition at line 2403 of file SDDS_utils.c.

                                     {
  char *name;
  if (!SDDS_VALID_TYPE(type))
    return NULL;
  if (!SDDS_CopyString(&name, SDDS_type_name[type - 1]))
    return NULL;
  return name;
}

SDDS_GetTypeSize()

epicsShareFuncSDDS int32_t SDDS_GetTypeSize ( int32_t type )

extern

Retrieves the size in bytes of a specified SDDS data type.

This function returns the size, in bytes, of the specified SDDS data type. The size corresponds to the memory footprint of the data type when stored in the dataset.

Parameters

[in]

type

The SDDS data type for which the size is requested. Must be one of the predefined constants: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING

Returns

On success, returns a positive integer representing the size of the data type in bytes. On failure (e.g., if the type is invalid), returns -1 and records an error message.

Note

The function relies on the SDDS_type_size array, which should be properly initialized with the sizes of all supported SDDS data types.

See also

SDDS_GetTypeName

SDDS_SetError

Definition at line 2374 of file SDDS_utils.c.

                                       {
  if (!SDDS_VALID_TYPE(type))
    return (-1);
  return (SDDS_type_size[type - 1]);
}

SDDS_GetValue()

epicsShareFuncSDDS void * SDDS_GetValue ( SDDS_DATASET * SDDS_dataset, char * column_name, int64_t srow_index, void * memory )

extern

Retrieves the value from a specified column and selected row, optionally storing it in provided memory.

This function accesses the value of a specific column and selected row within the current data table of a dataset. It returns the value as a pointer to the data, allowing for both direct access and optional storage in user-provided memory.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which the value is to be retrieved.
srow_index	Zero-based index representing the position of the selected row among all rows marked as "of interest".
memory	Pointer to user-allocated memory where the retrieved value will be stored. If NULL, the function allocates memory internally, and the caller is responsible for freeing it.

Returns

• Pointer to the retrieved value stored in memory (if provided) or in newly allocated memory.
• NULL if an error occurs (e.g., invalid dataset, unrecognized column name, undefined data type, memory allocation failure, invalid row index). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function allocates memory that the caller must free to prevent memory leaks.
• The function does not perform type casting. Ensure that the provided memory is of the appropriate type matching the column's data type.
• Modifying the data through the returned pointer affects the internal state of the dataset. Use with caution to avoid unintended side effects.

Note

• For columns containing string data (SDDS_STRING), the function copies the string into memory. A typical usage would involve passing a pointer to a char* variable. c char *string; SDDS_GetValue(&SDDS_dataset, "name", index, &string); // or string = *(char**)SDDS_GetValue(&SDDS_dataset, "name", index, NULL);
• The number of rows marked as "of interest" can be obtained using SDDS_CountRowsOfInterest.

See also

• SDDS_GetValueAsDouble
• SDDS_GetSelectedRowIndex
• SDDS_CountRowsOfInterest

Definition at line 1755 of file SDDS_extract.c.

                                                                                                     {
  int32_t type, size, column_index;
  int64_t row_index;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetValue"))
    return (NULL);
  if ((column_index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get value--column name is not recognized (SDDS_GetValue)");
    return (NULL);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, column_index))) {
    SDDS_SetError("Unable to get value--data type undefined (SDDS_GetValue)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if ((row_index = SDDS_GetSelectedRowIndex(SDDS_dataset, srow_index)) < 0) {
    SDDS_SetError("Unable to get value--row index out of range (SDDS_GetValue)");
    return (NULL);
  }
  if (type != SDDS_STRING) {
    if (!memory && !(memory = SDDS_Malloc(size))) {
      SDDS_SetError("Unable to get value--memory allocation failure (SDDS_GetValue)");
      return (NULL);
    }
    memcpy(memory, (char *)SDDS_dataset->data[column_index] + row_index * size, size);
    return (memory);
  }
  /* for character string data, a typical call would be
   * char *string;
   * SDDS_GetValue(&SDDS_dataset, "name", index, &string)    or
   * string = *(char**)SDDS_GetValue(&SDDS_dataset, "name", index, NULL)
   */
  if (!memory && !(memory = SDDS_Malloc(size))) {
    SDDS_SetError("Unable to get value--memory allocation failure (SDDS_GetValue)");
    return (NULL);
  }
  if (SDDS_CopyString(memory, ((char **)SDDS_dataset->data[column_index])[row_index]))
    return (memory);
  return (NULL);
}

SDDS_GetValueAsDouble()

epicsShareFuncSDDS double SDDS_GetValueAsDouble ( SDDS_DATASET * SDDS_dataset, char * column_name, int64_t srow_index )

extern

Retrieves the value from a specified column and selected row, casting it to a double.

This function accesses the value of a specific column and selected row within the current data table of a dataset. It casts the retrieved value to a double before returning it.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_name	NULL-terminated string specifying the name of the column from which the value is to be retrieved.
srow_index	Zero-based index representing the position of the selected row among all rows marked as "of interest".

Returns

• Double representing the casted value from the specified column and row.
• 0 if an error occurs (e.g., invalid dataset, unrecognized column name, undefined data type, invalid row index, non-numeric column type). In this case, an error message is recorded internally.

Warning

• This function only supports numerical data types. Attempting to retrieve and cast data from non-numeric columns (excluding SDDS_CHARACTER) will result in an error.

Note

• The function internally allocates temporary memory to store the value before casting. This memory is freed before the function returns.

See also

• SDDS_GetValue
• SDDS_GetSelectedRowIndex
• SDDS_CountRowsOfInterest

Definition at line 1822 of file SDDS_extract.c.

                                                                                                {
  int32_t type, size, column_index;
  int64_t row_index;
  void *memory;
  double value = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetValueAsDouble"))
    return (0);
  if ((column_index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get value--column name is not recognized (SDDS_GetValueAsDouble)");
    return (0);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, column_index))) {
    SDDS_SetError("Unable to get value--data type undefined (SDDS_GetValueAsDouble)");
    return (0);
  }
  size = SDDS_type_size[type - 1];
  if ((row_index = SDDS_GetSelectedRowIndex(SDDS_dataset, srow_index)) < 0) {
    SDDS_SetError("Unable to get value--row index out of range (SDDS_GetValueAsDouble)");
    return (0);
  }
  if ((type != SDDS_STRING) && (type != SDDS_CHARACTER)) {
    memory = SDDS_Malloc(size);
    memcpy(memory, (char *)SDDS_dataset->data[column_index] + row_index * size, size);
    switch (type) {
    case SDDS_SHORT:
      value = *(short *)memory;
      break;
    case SDDS_USHORT:
      value = *(unsigned short *)memory;
      break;
    case SDDS_LONG:
      value = *(int32_t *)memory;
      break;
    case SDDS_ULONG:
      value = *(uint32_t *)memory;
      break;
    case SDDS_LONG64:
      value = *(int64_t *)memory;
      break;
    case SDDS_ULONG64:
      value = *(uint64_t *)memory;
      break;
    case SDDS_FLOAT:
      value = *(float *)memory;
      break;
    case SDDS_DOUBLE:
      value = *(double *)memory;
      break;
    case SDDS_LONGDOUBLE:
      value = *(long double *)memory;
      break;
    }
    free(memory);
    return (value);
  }
  SDDS_SetError("Unable to get non-numeric value as double (SDDS_GetValueAsDouble)");
  return (0);
}

SDDS_GetValueByAbsIndex()

epicsShareFuncSDDS void * SDDS_GetValueByAbsIndex ( SDDS_DATASET * SDDS_dataset, int32_t column_index, int64_t row_index, void * memory )

extern

Retrieves the value from a specified column and absolute row index, optionally storing it in provided memory.

This function accesses the value of a specific column (identified by its index) and an absolute row index within the current data table of a dataset. The retrieved value is either copied into user-provided memory or returned as a direct pointer to the internal data.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_index	Zero-based index of the column from which the value is to be retrieved. Must be within the range [0, n_columns-1].
row_index	Absolute zero-based row index within the dataset's data table. Must be within the range [0, n_rows-1].
memory	Pointer to user-allocated memory where the retrieved value will be stored. If NULL, the function returns a pointer to the internal data.

Returns

• Pointer to the retrieved value stored in memory (if provided) or to the internal data.
• NULL if an error occurs (e.g., invalid dataset, column index out of range, row index out of range, undefined data type, memory allocation failure, non-numeric column type). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function returns a direct pointer to the internal data. Modifying the data through this pointer affects the dataset's internal state.
• If memory is provided, ensure that it points to sufficient memory to hold the data type of the column.
• This function does not perform type casting. Ensure that the memory type matches the column's data type.

Note

• Unlike SDDS_GetValueByIndex, this function uses an absolute row index rather than a selected row index among rows marked as "of interest".
• For columns containing string data (SDDS_STRING), the function copies the string into memory. A typical usage would involve passing a pointer to a char* variable. c char *string; SDDS_GetValueByAbsIndex(&SDDS_dataset, column_index, row_index, &string); // or string = *(char**)SDDS_GetValueByAbsIndex(&SDDS_dataset, column_index, row_index, NULL);

See also

• SDDS_GetValue
• SDDS_GetValueAsDouble
• SDDS_CountRowsOfInterest

Definition at line 2091 of file SDDS_extract.c.

                                                                                                                 {
  int32_t type, size;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetValueByAbsIndex"))
    return (NULL);
  if (column_index < 0 || column_index >= SDDS_dataset->layout.n_columns) {
    SDDS_SetError("Unable to get value--column index out of range (SDDS_GetValueByAbsIndex)");
    return (NULL);
  }
  if (row_index < 0 || row_index >= SDDS_dataset->n_rows) {
    SDDS_SetError("Unable to get value--index out of range (SDDS_GetValueByAbsIndex)");
    return (NULL);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, column_index))) {
    SDDS_SetError("Unable to get value--data type undefined (SDDS_GetValueByAbsIndex)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if (type != SDDS_STRING) {
    if (memory) {
      memcpy(memory, (char *)SDDS_dataset->data[column_index] + row_index * size, size);
      return (memory);
    }
    return ((char *)SDDS_dataset->data[column_index] + row_index * size);
  }
  /* for character string data, a typical call would be
   * char *string;
   * SDDS_GetValueByAbsIndex(&SDDS_dataset, cindex, index, &string)    or
   * string = *(char**)SDDS_GetValue(&SDDS_dataset, cindex, index, NULL)
   */
  if (!memory)
    memory = SDDS_Malloc(size);
  if (SDDS_CopyString(memory, ((char **)SDDS_dataset->data[column_index])[row_index]))
    return (memory);
  return (NULL);
}

SDDS_GetValueByIndex()

epicsShareFuncSDDS void * SDDS_GetValueByIndex ( SDDS_DATASET * SDDS_dataset, int32_t column_index, int64_t srow_index, void * memory )

extern

Retrieves the value from a specified column and selected row, optionally storing it in provided memory.

This function accesses the value of a specific column (identified by its index) and a selected row (identified by its selected row index among rows marked as "of interest") within the current data table of a dataset. The retrieved value is either copied into user-provided memory or returned as a direct pointer to the internal data.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_index	Zero-based index of the column from which the value is to be retrieved. Must be within the range [0, n_columns-1].
srow_index	Zero-based index representing the position of the selected row among all rows marked as "of interest".
memory	Pointer to user-allocated memory where the retrieved value will be stored. If NULL, the function returns a pointer to the internal data.

Returns

• Pointer to the retrieved value stored in memory (if provided) or to the internal data.
• NULL if an error occurs (e.g., invalid dataset, column index out of range, undefined data type, row index out of range, memory allocation failure, non-numeric column type). In this case, an error message is recorded internally.

Warning

• If memory is NULL, the function returns a direct pointer to the internal data. Modifying the data through this pointer affects the dataset's internal state.
• If memory is provided, ensure that it points to sufficient memory to hold the data type of the column.
• This function does not perform type casting. Ensure that the memory type matches the column's data type.

Note

• For columns containing string data (SDDS_STRING), the function copies the string into memory. A typical usage would involve passing a pointer to a char* variable. c char *string; SDDS_GetValueByIndex(&SDDS_dataset, column_index, index, &string); // or string = *(char**)SDDS_GetValueByIndex(&SDDS_dataset, column_index, index, NULL);
• The number of rows marked as "of interest" can be obtained using SDDS_CountRowsOfInterest.

See also

• SDDS_GetValue
• SDDS_GetValueAsDouble
• SDDS_GetSelectedRowIndex
• SDDS_CountRowsOfInterest

Definition at line 2015 of file SDDS_extract.c.

                                                                                                               {
  int32_t type, size;
  int64_t row_index;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetValueByIndex"))
    return (NULL);
  if (column_index < 0 || column_index >= SDDS_dataset->layout.n_columns) {
    SDDS_SetError("Unable to get value--column index out of range (SDDS_GetValueByIndex)");
    return (NULL);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, column_index))) {
    SDDS_SetError("Unable to get value--data type undefined (SDDS_GetValueByIndex)");
    return (NULL);
  }
  size = SDDS_type_size[type - 1];
  if ((row_index = SDDS_GetSelectedRowIndex(SDDS_dataset, srow_index)) < 0) {
    SDDS_SetError("Unable to get value--row index out of range (SDDS_GetValueByIndex)");
    return (NULL);
  }
  if (type != SDDS_STRING) {
    if (memory) {
      memcpy(memory, (char *)SDDS_dataset->data[column_index] + row_index * size, size);
      return (memory);
    }
    return ((char *)SDDS_dataset->data[column_index] + row_index * size);
  }
  /* for character string data, a typical call would be
   * char *string;
   * SDDS_GetValueByIndex(&SDDS_dataset, cindex, index, &string)    or
   * string = *(char**)SDDS_GetValue(&SDDS_dataset, cindex, index, NULL)
   */
  if (!memory)
    memory = SDDS_Malloc(size);
  if (SDDS_CopyString(memory, ((char **)SDDS_dataset->data[column_index])[row_index]))
    return (memory);
  return (NULL);
}

SDDS_GetValueByIndexAsDouble()

epicsShareFuncSDDS double SDDS_GetValueByIndexAsDouble ( SDDS_DATASET * SDDS_dataset, int32_t column_index, int64_t srow_index )

extern

Retrieves the value from a specified column and selected row, casting it to a double.

This function accesses the value of a specific column (identified by its index) and a selected row (identified by its selected row index among rows marked as "of interest") within the current data table of a dataset. It casts the retrieved value to a double before returning it.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_index	Zero-based index of the column from which the value is to be retrieved. Must be within the range [0, n_columns-1].
srow_index	Zero-based index representing the position of the selected row among all rows marked as "of interest".

Returns

• Double representing the casted value from the specified column and row.
• 0.0 if an error occurs (e.g., invalid dataset, column index out of range, undefined data type, row index out of range, non-numeric column type). In this case, an error message is recorded internally.

Warning

• This function only supports numerical data types. Attempting to retrieve and cast data from non-numeric columns (excluding SDDS_CHARACTER) will result in an error.
• The returned value 0.0 may be ambiguous if it is a valid data value. Always check for errors using SDDS_CheckError or similar mechanisms.

Note

• The number of rows marked as "of interest" can be obtained using SDDS_CountRowsOfInterest.
• If the dataset's memory mode for the column is set to DONT_TRACK_COLUMN_MEMORY_AFTER_ACCESS, the internal data for the column may be freed after access.

See also

• SDDS_GetValue
• SDDS_GetValueAsDouble
• SDDS_GetSelectedRowIndex
• SDDS_CountRowsOfInterest

Definition at line 1915 of file SDDS_extract.c.

                                                                                                          {
  int32_t type, size;
  int64_t row_index;
  void *memory;
  double value = 0;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GetValueByIndexAsDouble"))
    return (0);
  if (column_index < 0 || column_index >= SDDS_dataset->layout.n_columns) {
    SDDS_SetError("Unable to get value--column index out of range (SDDS_GetValueByIndexAsDouble)");
    return (0);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, column_index))) {
    SDDS_SetError("Unable to get value--data type undefined (SDDS_GetValueByIndexAsDouble)");
    return (0);
  }
  size = SDDS_type_size[type - 1];
  if ((row_index = SDDS_GetSelectedRowIndex(SDDS_dataset, srow_index)) < 0) {
    SDDS_SetError("Unable to get value--row index out of range (SDDS_GetValueByIndexAsDouble)");
    return (0);
  }
  if ((type != SDDS_STRING) && (type != SDDS_CHARACTER)) {
    memory = SDDS_Malloc(size);
    memcpy(memory, (char *)SDDS_dataset->data[column_index] + row_index * size, size);
    switch (type) {
    case SDDS_SHORT:
      value = *(short *)memory;
      break;
    case SDDS_USHORT:
      value = *(unsigned short *)memory;
      break;
    case SDDS_LONG:
      value = *(int32_t *)memory;
      break;
    case SDDS_ULONG:
      value = *(uint32_t *)memory;
      break;
    case SDDS_LONG64:
      value = *(int64_t *)memory;
      break;
    case SDDS_ULONG64:
      value = *(uint64_t *)memory;
      break;
    case SDDS_FLOAT:
      value = *(float *)memory;
      break;
    case SDDS_DOUBLE:
      value = *(double *)memory;
      break;
    case SDDS_LONGDOUBLE:
      value = *(long double *)memory;
      break;
    }
    free(memory);
    return (value);
  }
  SDDS_SetError("Unable to get non-numeric value as double (SDDS_GetValueByIndexAsDouble)");
  return (0);
}

SDDS_GotoPage()

epicsShareFuncSDDS int32_t SDDS_GotoPage ( SDDS_DATASET * SDDS_dataset, int32_t page_number )

extern

Sets the current page of the SDDS dataset to the specified page number.

This function is used to navigate to a specific page of the SDDS dataset. It is only supported for non-zip files and does not work for pipe input.

Parameters

SDDS_dataset	The SDDS dataset to operate on.
page_number	The page number to navigate to.

Returns

Returns 1 on success, 0 on failure.

Definition at line 1273 of file SDDS_input.c.

                                                                       {
  int64_t offset;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_GotoPage"))
    return (0);
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't go to page--file is disconnected (SDDS_GotoPage)");
    return 0;
  }
  if (SDDS_dataset->layout.popenUsed || !SDDS_dataset->layout.filename) {
    SDDS_SetError("Can't go to page of pipe is used (SDDS_GotoPage)");
    return 0;
  }
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    SDDS_SetError("Can not go to page of a gzip file (SDDS_GotoPage)");
    return (0);
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      SDDS_SetError("Can not go to page of an .lzma or .xz file (SDDS_GotoPage)");
      return (0);
    } else {
      if (!SDDS_dataset->layout.fp) {
        SDDS_SetError("Unable to go to page--NULL file pointer (SDDS_GotoPage)");
        return (0);
      }
    }
#if defined(zLib)
  }
#endif
  if (!SDDS_dataset->layout.filename) {
    SDDS_SetError("Can't go to page--NULL filename pointer (SDDS_GotoPage)");
    return 0;
  }
  if (SDDS_dataset->mode != SDDS_READMODE) {
    SDDS_SetError("Can't go to page--file mode has to be reading mode (SDDS_GotoPage)");
    return 0;
  }
  if (SDDS_dataset->fBuffer.bufferSize) {
    SDDS_SetError("Can't go to page--file buffering is turned on (SDDS_GotoPage)");
    return 0;
  }
  if (page_number < 1) {
    SDDS_SetError("The page_number can not be less than 1 (SDDS_GotoPage)");
    return (0);
  }
  if (page_number > SDDS_dataset->pages_read) {
    offset = SDDS_dataset->pagecount_offset[SDDS_dataset->pages_read] - ftell(SDDS_dataset->layout.fp);
    fseek(SDDS_dataset->layout.fp, offset, 1);
    SDDS_dataset->page_number = SDDS_dataset->pages_read;
    while (SDDS_dataset->pages_read < page_number) {
      if (SDDS_ReadPageSparse(SDDS_dataset, 0, SDDS_dataset->layout.data_mode.column_major ? 1 : 10000, 0, 0) <= 0) {
        SDDS_SetError("The page_number is greater than the total pages (SDDS_GotoPage)");
        return (0);
      }
    }
  } else {
    offset = SDDS_dataset->pagecount_offset[page_number - 1] - ftell(SDDS_dataset->layout.fp);
    fseek(SDDS_dataset->layout.fp, offset, 1); /*seek to the position from current offset */
    SDDS_dataset->page_number = page_number - 1;
  }
  return 1;
}

SDDS_HasWhitespace()

epicsShareFuncSDDS int32_t SDDS_HasWhitespace ( char * string )

extern

Checks if a string contains any whitespace characters.

This function scans through the provided string to determine if it contains any whitespace characters (e.g., space, tab, newline).

Parameters

[in]

string

Pointer to the null-terminated string to be checked.

Returns

Returns 1 if the string contains at least one whitespace character. Returns 0 if no whitespace characters are found or if the input string is NULL.

See also

isspace

Definition at line 1488 of file SDDS_utils.c.

                                         {
  if (!string)
    return (0);
  while (*string) {
    if (isspace(*string))
      return (1);
    string++;
  }
  return (0);
}

SDDS_IdentifyType()

epicsShareFuncSDDS int32_t SDDS_IdentifyType ( char * typeName )

extern

Identifies the SDDS data type based on its string name.

This function searches for the SDDS data type that matches the provided string typeName. It returns the corresponding SDDS data type constant if a match is found.

Parameters

[in]

typeName

A null-terminated string representing the name of the SDDS data type to identify.

Returns

On success, returns the SDDS data type constant (int32_t) corresponding to typeName. On failure (e.g., if typeName does not match any known data type), returns 0.

Note

The function performs a case-sensitive comparison between typeName and the names of supported SDDS data types.

See also

SDDS_GetTypeName

SDDS_SetError

Definition at line 2426 of file SDDS_utils.c.

                                          {
  int32_t i;
  for (i = 0; i < SDDS_NUM_TYPES; i++)
    if (strcmp(typeName, SDDS_type_name[i]) == 0)
      return i + 1;
  return 0;
}

SDDS_InitializeAppend()

epicsShareFuncSDDS int32_t SDDS_InitializeAppend ( SDDS_DATASET * SDDS_dataset, const char * filename )

extern

Initializes the SDDS dataset for appending data by adding a new page to an existing file.

This function prepares the SDDS dataset for appending additional data to an existing SDDS file by initializing necessary data structures, verifying file integrity, and setting up for the addition of a new data page. It ensures that the file is writable, not compressed, and properly locked to prevent concurrent modifications.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be initialized for appending.
[in]	filename	The name of the existing SDDS file to which data will be appended. If NULL, data will be appended to standard input.

Returns

• 1 on successful initialization.
• 0 on error. In this case, an internal error message is set describing the failure.

Precondition

• The specified file must exist and be a valid SDDS file.
• The file must not be compressed (gzip, lzma, xz) and must be accessible for read and write operations.

Postcondition

• The dataset is ready to append data as a new page.
• The file is locked to prevent concurrent writes.

Note

• If filename is NULL, the dataset will append data from standard input.
• The function sets internal flags indicating whether the file was previously empty or had existing data.

Warning

• Appending to a compressed file is not supported and will result in an error.
• Ensure that no other processes are accessing the file simultaneously to avoid conflicts.

Definition at line 288 of file SDDS_output.c.

                                                                                {
  /*  char *ptr, *datafile, *headerfile; */
  char s[SDDS_MAXLINE];
  int64_t endOfLayoutOffset, endOfFileOffset;
  char *extension;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_InitializeAppend"))
    return 0;
  if (!SDDS_ZeroMemory((void *)SDDS_dataset, sizeof(SDDS_DATASET))) {
    sprintf(s, "Unable to initialize input for file %s--can't zero SDDS_DATASET structure (SDDS_InitializeAppend)", filename);
    SDDS_SetError(s);
    return 0;
  }
  SDDS_dataset->layout.popenUsed = SDDS_dataset->layout.gzipFile = SDDS_dataset->layout.lzmaFile = SDDS_dataset->layout.disconnected = 0;
  SDDS_dataset->layout.depth = SDDS_dataset->layout.data_command_seen = SDDS_dataset->layout.commentFlags = SDDS_dataset->deferSavingLayout = 0;
  if (!filename)
    SDDS_dataset->layout.filename = NULL;
  else if (!SDDS_CopyString(&SDDS_dataset->layout.filename, filename)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeAppend)", filename);
    SDDS_SetError(s);
    return 0;
  } else if ((extension = strrchr(filename, '.')) && ((strcmp(extension, ".gz") == 0) || (strcmp(extension, ".lzma") == 0) || (strcmp(extension, ".xz") == 0))) {
    sprintf(s, "Cannot append to a compressed file %s (SDDS_InitializeAppend)", filename);
    SDDS_SetError(s);
    return 0;
  }
 
  SDDS_dataset->layout.popenUsed = 0;
  if (!filename) {
#if defined(_WIN32)
    if (_setmode(_fileno(stdin), _O_BINARY) == -1) {
      sprintf(s, "unable to set stdin to binary mode");
      SDDS_SetError(s);
      return 0;
    }
#endif
    SDDS_dataset->layout.fp = stdin;
  } else {
    if (SDDS_FileIsLocked(filename)) {
      sprintf(s, "unable to open file %s for appending--file is locked (SDDS_InitializeAppend)", filename);
      SDDS_SetError(s);
      return 0;
    }
    if (!(SDDS_dataset->layout.fp = fopen(filename, FOPEN_READ_AND_WRITE_MODE))) {
      sprintf(s, "Unable to open file %s for appending (SDDS_InitializeAppend)", filename);
      SDDS_SetError(s);
      return 0;
    }
    if (!SDDS_LockFile(SDDS_dataset->layout.fp, filename, "SDDS_InitializeAppend"))
      return 0;
  }
 
  if (!SDDS_ReadLayout(SDDS_dataset, SDDS_dataset->layout.fp))
    return 0;
  endOfLayoutOffset = ftell(SDDS_dataset->layout.fp);
  if (SDDS_dataset->layout.n_columns &&
      (!(SDDS_dataset->column_flag = (int32_t *)SDDS_Malloc(sizeof(int32_t) * SDDS_dataset->layout.n_columns)) ||
       !(SDDS_dataset->column_order = (int32_t *)SDDS_Malloc(sizeof(int32_t) * SDDS_dataset->layout.n_columns)) ||
       !SDDS_SetMemory(SDDS_dataset->column_flag, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)1, (int32_t)0) ||
       !SDDS_SetMemory(SDDS_dataset->column_order, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)0, (int32_t)1))) {
    SDDS_SetError("Unable to initialize input--memory allocation failure (SDDS_InitializeAppend)");
    return 0;
  }
  if (fseek(SDDS_dataset->layout.fp, 0, 2) == -1) {
    SDDS_SetError("Unable to initialize append--seek failure (SDDS_InitializeAppend)");
    return 0;
  }
  endOfFileOffset = ftell(SDDS_dataset->layout.fp);
  if (endOfFileOffset == endOfLayoutOffset)
    SDDS_dataset->file_had_data = 0; /* appending to empty file */
  else
    SDDS_dataset->file_had_data = 1;       /* appending to nonempty file */
  SDDS_dataset->layout.layout_written = 1; /* its already in the file */
  SDDS_dataset->mode = SDDS_WRITEMODE;     /*writing */
  return 1;
}

SDDS_InitializeAppendToPage()

epicsShareFuncSDDS int32_t SDDS_InitializeAppendToPage ( SDDS_DATASET * SDDS_dataset, const char * filename, int64_t updateInterval, int64_t * rowsPresentReturn )

extern

Initializes the SDDS dataset for appending data to the last page of an existing file.

This function sets up the SDDS dataset to append additional data rows to the last page of an existing SDDS file. It reads the existing file layout, determines the current state of data (including row counts), and prepares internal data structures to accommodate new data. The function also handles file locking, buffer management, and ensures that the file is ready for efficient data appending based on the specified update interval.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be initialized for appending.
[in]	filename	The name of the existing SDDS file to which data will be appended. If NULL, data will be appended to standard input.
[in]	updateInterval	The number of rows to write before the dataset reallocates memory or flushes data. This parameter controls the frequency of memory allocation and disk I/O operations during the append process.
[out]	rowsPresentReturn	Pointer to an int64_t variable where the function will store the number of rows present in the dataset after initialization. This provides information on the current dataset size.

Returns

• 1 on successful initialization.
• 0 on error. In this case, an internal error message is set detailing the issue.

Precondition

• The specified file must exist and be a valid SDDS file.
• The file must not be compressed (gzip, lzma, xz) and must be accessible for read and write operations.

Postcondition

• The dataset is configured to append data to the last page of the file.
• Internal structures are initialized to track row counts and manage memory efficiently based on the update interval.
• The file is locked to prevent concurrent modifications.
• rowsPresentReturn is updated with the current number of rows in the dataset.

Note

• If filename is NULL, data will be appended from standard input.
• The function sets internal flags indicating whether the file already contained data prior to appending.

Warning

• Appending to a compressed file is not supported and will result in an error.
• Ensure that no other processes are accessing the file simultaneously to avoid conflicts.

Definition at line 397 of file SDDS_output.c.

                                                                                                                                          {
  /*  char *ptr, *datafile, *headerfile; */
  char s[SDDS_MAXLINE];
  int64_t endOfLayoutOffset, endOfFileOffset, rowCountOffset, offset;
  int32_t rowsPresent32;
  int64_t rowsPresent;
  char *extension;
  int32_t previousBufferSize;
 
  *rowsPresentReturn = -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_InitializeAppendToPage"))
    return 0;
  if (!SDDS_ZeroMemory((void *)SDDS_dataset, sizeof(SDDS_DATASET))) {
    sprintf(s, "Unable to initialize input for file %s--can't zero SDDS_DATASET structure (SDDS_InitializeAppendToPage)", filename);
    SDDS_SetError(s);
    return 0;
  }
  SDDS_dataset->layout.popenUsed = SDDS_dataset->layout.gzipFile = SDDS_dataset->layout.lzmaFile = SDDS_dataset->layout.disconnected = 0;
  SDDS_dataset->layout.depth = SDDS_dataset->layout.data_command_seen = SDDS_dataset->layout.commentFlags = SDDS_dataset->deferSavingLayout = 0;
  if (!filename)
    SDDS_dataset->layout.filename = NULL;
  else if (!SDDS_CopyString(&SDDS_dataset->layout.filename, filename)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeAppendToPage)", filename);
    SDDS_SetError(s);
    return 0;
  } else if ((extension = strrchr(filename, '.')) && ((strcmp(extension, ".gz") == 0) || (strcmp(extension, ".lzma") == 0) || (strcmp(extension, ".xz") == 0))) {
    sprintf(s, "Cannot append to a compressed file %s (SDDS_InitializeAppendToPage)", filename);
    SDDS_SetError(s);
    return 0;
  }
 
  if (!filename) {
#if defined(_WIN32)
    if (_setmode(_fileno(stdin), _O_BINARY) == -1) {
      sprintf(s, "unable to set stdin to binary mode");
      SDDS_SetError(s);
      return 0;
    }
#endif
    SDDS_dataset->layout.fp = stdin;
  } else {
    if (SDDS_FileIsLocked(filename)) {
      sprintf(s, "unable to open file %s for appending--file is locked (SDDS_InitializeAppendToPage)", filename);
      SDDS_SetError(s);
      return 0;
    }
    if (!(SDDS_dataset->layout.fp = fopen(filename, FOPEN_READ_AND_WRITE_MODE))) {
      sprintf(s, "Unable to open file %s for appending (SDDS_InitializeAppendToPage)", filename);
      SDDS_SetError(s);
      return 0;
    }
    if (!SDDS_LockFile(SDDS_dataset->layout.fp, filename, "SDDS_InitializeAppendToPage")) {
      return 0;
    }
  }
 
  if (!SDDS_ReadLayout(SDDS_dataset, SDDS_dataset->layout.fp)) {
    return 0;
  }
  endOfLayoutOffset = ftell(SDDS_dataset->layout.fp);
  if (SDDS_dataset->layout.n_columns &&
      (!(SDDS_dataset->column_flag = (int32_t *)SDDS_Malloc(sizeof(int32_t) * SDDS_dataset->layout.n_columns)) ||
       !(SDDS_dataset->column_order = (int32_t *)SDDS_Malloc(sizeof(int32_t) * SDDS_dataset->layout.n_columns)) ||
       !SDDS_SetMemory(SDDS_dataset->column_flag, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)1, (int32_t)0) ||
       !SDDS_SetMemory(SDDS_dataset->column_order, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)0, (int32_t)1))) {
    SDDS_SetError("Unable to initialize input--memory allocation failure (SDDS_InitializeAppendToPage)");
    return 0;
  }
  rowCountOffset = -1;
  rowsPresent = 0;
#ifdef DEBUG
  fprintf(stderr, "Data mode is %s\n", SDDS_data_mode[SDDS_dataset->layout.data_mode.mode - 1]);
#endif
  SDDS_dataset->pagecount_offset = NULL;
  previousBufferSize = SDDS_SetDefaultIOBufferSize(0);
  if (!SDDS_dataset->layout.data_mode.no_row_counts) {
    /* read pages to get to the last page */
    while (SDDS_ReadPageSparse(SDDS_dataset, 0, 10000, 0, 0) > 0) {
      rowCountOffset = SDDS_dataset->rowcount_offset;
      offset = ftell(SDDS_dataset->layout.fp);
      fseek(SDDS_dataset->layout.fp, rowCountOffset, 0);
 
      if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY) {
        if (fread(&rowsPresent32, sizeof(rowsPresent32), 1, SDDS_dataset->layout.fp) == 0) {
          SDDS_SetError("Error: row count not present or not correct length");
          return 0;
        }
        if (SDDS_dataset->swapByteOrder) {
          SDDS_SwapLong(&rowsPresent32);
        }
        if (rowsPresent32 == INT32_MIN) {
          if (fread(&rowsPresent, sizeof(rowsPresent), 1, SDDS_dataset->layout.fp) == 0) {
            SDDS_SetError("Error: row count not present or not correct length");
            return 0;
          }
          if (SDDS_dataset->swapByteOrder) {
            SDDS_SwapLong64(&rowsPresent);
          }
        } else {
          rowsPresent = rowsPresent32;
        }
      } else {
        char buffer[30];
        if (!fgets(buffer, 30, SDDS_dataset->layout.fp) || strlen(buffer) != 21 || sscanf(buffer, "%" SCNd64, &rowsPresent) != 1) {
#ifdef DEBUG
          fprintf(stderr, "buffer for row count data: >%s<\n", buffer);
#endif
          SDDS_SetError("Unable to initialize input--row count not present or not correct length (SDDS_InitializeAppendToPage)");
          SDDS_SetDefaultIOBufferSize(previousBufferSize);
          return 0;
        }
      }
      fseek(SDDS_dataset->layout.fp, offset, 0);
#ifdef DEBUG
      fprintf(stderr, "%" PRId64 " rows present\n", rowsPresent);
#endif
    }
    if (rowCountOffset == -1) {
      SDDS_SetDefaultIOBufferSize(previousBufferSize);
      SDDS_SetError("Unable to initialize input--problem finding row count offset (SDDS_InitializeAppendToPage)");
      return 0;
    }
  }
  SDDS_SetDefaultIOBufferSize(previousBufferSize);
  SDDS_dataset->fBuffer.bytesLeft = SDDS_dataset->fBuffer.bufferSize;
 
#ifdef DEBUG
  fprintf(stderr, "Starting page with %" PRId64 " rows\n", updateInterval);
#endif
  if (!SDDS_StartPage(SDDS_dataset, updateInterval)) {
    SDDS_SetError("Unable to initialize input--problem starting page (SDDS_InitializeAppendToPage)");
    return 0;
  }
 
  /* seek to the end of the file */
  if (fseek(SDDS_dataset->layout.fp, 0, 2) == -1) {
    SDDS_SetError("Unable to initialize append--seek failure (SDDS_InitializeAppendToPage)");
    return 0;
  }
  endOfFileOffset = ftell(SDDS_dataset->layout.fp);
  if (endOfFileOffset == endOfLayoutOffset)
    SDDS_dataset->file_had_data = 0; /* appending to empty file */
  else {
    SDDS_dataset->file_had_data = 1; /* appending to nonempty file */
    if (rowCountOffset != -1) {
      SDDS_dataset->rowcount_offset = rowCountOffset;
      SDDS_dataset->n_rows_written = rowsPresent;
      SDDS_dataset->first_row_in_mem = rowsPresent;
      SDDS_dataset->last_row_written = -1;
      *rowsPresentReturn = rowsPresent;
      SDDS_dataset->writing_page = 1;
    }
  }
#ifdef DEBUG
  fprintf(stderr, "rowcount_offset = %" PRId64 ", n_rows_written = %" PRId64 ", first_row_in_mem = %" PRId64 ", last_row_written = %" PRId64 "\n", SDDS_dataset->rowcount_offset, SDDS_dataset->n_rows_written, SDDS_dataset->first_row_in_mem, SDDS_dataset->last_row_written);
#endif
  SDDS_dataset->page_number = 1;
  SDDS_dataset->layout.layout_written = 1; /* its already in the file */
  SDDS_dataset->mode = SDDS_WRITEMODE;     /*writing */
  return 1;
}

SDDS_InitializeCopy()

epicsShareFuncSDDS int32_t SDDS_InitializeCopy ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source, char * filename, char * filemode )

extern

Initializes an SDDS_DATASET structure in preparation for copying a data table from another SDDS_DATASET structure.

Parameters

SDDS_target	Address of SDDS_DATASET structure into which to copy data.
SDDS_source	Address of SDDS_DATASET structure from which to copy data.
filename	A NULL-terminated character string giving a filename to be associated with the new SDDS_DATASET. Typically, the name of a file to which the copied data will be written after modification. Ignored if NULL.
filemode	A NULL-terminated character string giving the fopen file mode to be used to open the file named by filename. Ignored if filename is NULL.

Returns

1 on success. On failure, returns 0 and records an error message.

Definition at line 40 of file SDDS_copy.c.

                                                                                                                  {
  char s[SDDS_MAXLINE];
#if defined(zLib)
  char *extension;
#endif
 
  if (sizeof(gzFile) != sizeof(void *)) {
    SDDS_SetError("gzFile is not the same size as void *, possible corruption of the SDDS_LAYOUT structure");
    return (0);
  }
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_InitializeCopy"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_InitializeCopy"))
    return (0);
  if (!SDDS_ZeroMemory((void *)SDDS_target, sizeof(SDDS_DATASET))) {
    SDDS_SetError("Unable to copy layout--can't zero SDDS_DATASET structure (SDDS_InitializeCopy)");
    return (0);
  }
  if (strcmp(filemode, "r") == 0) {
    filemode = FOPEN_READ_MODE;
    SDDS_target->mode = SDDS_READMODE;
  } else if (strcmp(filemode, "w") == 0) {
    filemode = FOPEN_WRITE_MODE;
    SDDS_target->mode = SDDS_WRITEMODE;
  }
  SDDS_target->pagecount_offset = NULL;
  if (!(strcmp(filemode, "r") == 0 || strcmp(filemode, "w") == 0 || strcmp(filemode, "rb") == 0 || strcmp(filemode, "wb") == 0 || strcmp(filemode, "m") == 0)) {
    SDDS_SetError("Programming error--invalid file mode (SDDS_InitializeCopy)");
    return (0);
  }
 
  SDDS_target->layout.popenUsed = 0;
  SDDS_target->layout.gzipFile = 0;
  SDDS_target->layout.lzmaFile = 0;
  if (filename) {
    if (SDDS_FileIsLocked(filename)) {
      sprintf(s, "unable to open file %s for copy--file is locked (SDDS_InitializeCopy)", filename);
      SDDS_SetError(s);
      return 0;
    }
 
    if ((extension = strrchr(filename, '.')) && ((strcmp(extension, ".xz") == 0) || (strcmp(extension, ".lzma") == 0))) {
      SDDS_target->layout.lzmaFile = 1;
      if (!filemode) {
        sprintf(s, "Unable to open file %s (SDDS_InitializeCopy)", filename);
        SDDS_SetError(s);
        return (0);
      }
      if (!(SDDS_target->layout.lzmafp = lzma_open(filename, filemode))) {
        sprintf(s, "Unable to open file %s for writing (SDDS_InitializeCopy)", filename);
        SDDS_SetError(s);
        return 0;
      }
      SDDS_target->layout.fp = SDDS_target->layout.lzmafp->fp;
    } else {
      if (!filemode || !(SDDS_target->layout.fp = fopen(filename, filemode))) {
        sprintf(s, "Unable to open file %s (SDDS_InitializeCopy)", filename);
        SDDS_SetError(s);
        return (0);
      }
    }
    if ((strcmp(filemode, "w") == 0 || strcmp(filemode, "wb") == 0) && !SDDS_LockFile(SDDS_target->layout.fp, filename, "SDDS_InitializeCopy"))
      return 0;
    if (!SDDS_CopyString(&SDDS_target->layout.filename, filename)) {
      SDDS_SetError("Memory allocation failure (SDDS_InitializeCopy)");
      return (0);
    }
#if defined(zLib)
    if ((extension = strrchr(filename, '.')) && strcmp(extension, ".gz") == 0) {
      SDDS_target->layout.gzipFile = 1;
      if ((SDDS_target->layout.gzfp = gzdopen(fileno(SDDS_target->layout.fp), filemode)) == NULL) {
        sprintf(s, "Unable to open compressed file %s for writing (SDDS_InitializeCopy)", filename);
        SDDS_SetError(s);
        return 0;
      }
    }
#endif
  } else {
    SDDS_target->layout.filename = NULL;
    SDDS_target->layout.fp = NULL;
    SDDS_target->mode = SDDS_MEMMODE;
    if (filemode) {
      if (strcmp(filemode, "w") == 0 || strcmp(filemode, "wb") == 0)
        SDDS_target->layout.fp = stdout;
      else if (strcmp(filemode, "r") == 0 || strcmp(filemode, "rb") == 0)
        SDDS_target->layout.fp = stdin;
 
        /*      else if (strcmp(filemode, "m")!=0) {
                  SDDS_SetError("Unknown filemode (SDDS_InitializeCopy)");
                  return(0);
                  } */
#if defined(_WIN32)
      if (strcmp(filemode, "m") != 0) {
        if (_setmode(_fileno(SDDS_target->layout.fp), _O_BINARY) == -1) {
          sprintf(s, "unable to set stdout or stdin to binary mode");
          SDDS_SetError(s);
          return 0;
        }
      }
#endif
    }
  }
  SDDS_target->page_number = SDDS_target->page_started = 0;
  if (!SDDS_CopyLayout(SDDS_target, SDDS_source))
    return (0);
  return (1);
}

SDDS_InitializeHeaderlessInput()

epicsShareFuncSDDS int32_t SDDS_InitializeHeaderlessInput ( SDDS_DATASET * SDDS_dataset, char * filename )

extern

Initializes the SDDS dataset for headerless input.

This function initializes the SDDS dataset structure for reading data from a file without a header.

Parameters

SDDS_dataset	A pointer to the SDDS_DATASET structure to be initialized.
filename	The name of the file to read data from.

Returns

Returns 1 on success, 0 on failure.

Definition at line 176 of file SDDS_input.c.

                                                                                   {
  /*  char *ptr, *datafile; */
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_InitializeInput"))
    return (0);
  if (!SDDS_ZeroMemory((void *)SDDS_dataset, sizeof(SDDS_DATASET))) {
    SDDS_SetError("Unable to initialize input--can't zero SDDS_DATASET structure (SDDS_InitializeInput)");
    return (0);
  }
  SDDS_dataset->layout.gzipFile = SDDS_dataset->layout.lzmaFile = 0;
  SDDS_dataset->layout.depth = SDDS_dataset->layout.data_command_seen = SDDS_dataset->layout.commentFlags = SDDS_dataset->deferSavingLayout = 0;
  if (!(SDDS_dataset->layout.fp = fopen(filename, FOPEN_READ_MODE))) {
    SDDS_SetError("Unable to open file (SDDS_InitializeInput)");
    return (0);
  }
  if (!SDDS_CopyString(&SDDS_dataset->layout.filename, filename)) {
    SDDS_SetError("Memory allocation failure (SDDS_InitializeInput)");
    return (0);
  }
  SDDS_dataset->mode = SDDS_READMODE; /*reading */
  SDDS_dataset->page_number = SDDS_dataset->page_started = 0;
  SDDS_dataset->pages_read = 0;
  SDDS_dataset->pagecount_offset = malloc(sizeof(*SDDS_dataset->pagecount_offset));
  SDDS_dataset->pagecount_offset[0] = ftell(SDDS_dataset->layout.fp);
  fseek(SDDS_dataset->layout.fp, 0, 2); /*point to the end of the file */
  SDDS_dataset->endOfFile_offset = ftell(SDDS_dataset->layout.fp);
  fseek(SDDS_dataset->layout.fp, SDDS_dataset->pagecount_offset[0], 0);
  /*point to the beginning of the first page */
  return (1);
}

SDDS_InitializeInput()

epicsShareFuncSDDS int32_t SDDS_InitializeInput ( SDDS_DATASET * SDDS_dataset, char * filename )

extern

Initializes a SDDS_DATASET structure for use in reading data from a SDDS file. This involves opening the file and reading the SDDS header.

Parameters

SDDS_dataset	Address of the SDDS_DATASET structure for the data set.
filename	A NULL-terminated character string giving the name of the file to set up for input.

Returns

1 on success. On failure, returns 0 and records an error message.

Definition at line 50 of file SDDS_input.c.

                                                                         {
  /*  char *ptr, *datafile, *headerfile; */
  char s[SDDS_MAXLINE];
#if defined(zLib)
  char *extension;
#endif
  if (sizeof(gzFile) != sizeof(void *)) {
    SDDS_SetError("gzFile is not the same size as void *, possible corruption of the SDDS_LAYOUT structure");
    return (0);
  }
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_InitializeInput"))
    return (0);
 
  if (!SDDS_ZeroMemory((void *)SDDS_dataset, sizeof(SDDS_DATASET))) {
    sprintf(s, "Unable to initialize input for file %s--can't zero SDDS_DATASET structure (SDDS_InitializeInput)", filename);
    SDDS_SetError(s);
    return (0);
  }
  SDDS_dataset->layout.gzipFile = SDDS_dataset->layout.lzmaFile = SDDS_dataset->layout.disconnected = SDDS_dataset->layout.popenUsed = 0;
  SDDS_dataset->layout.depth = SDDS_dataset->layout.data_command_seen = SDDS_dataset->layout.commentFlags = SDDS_dataset->deferSavingLayout = 0;
  SDDS_dataset->layout.data_mode.column_memory_mode = DEFAULT_COLUMN_MEMORY_MODE;
  if (!filename)
    SDDS_dataset->layout.filename = NULL;
  else if (!SDDS_CopyString(&SDDS_dataset->layout.filename, filename)) {
    sprintf(s, "Memory allocation failure initializing file \"%s\" (SDDS_InitializeInput)", filename);
    SDDS_SetError(s);
    return (0);
  }
  if (!filename) {
#if defined(_WIN32)
    if (_setmode(_fileno(stdin), _O_BINARY) == -1) {
      sprintf(s, "unable to set stdin to binary mode");
      SDDS_SetError(s);
      return 0;
    }
#endif
    SDDS_dataset->layout.fp = stdin;
  } else {
#if defined(zLib)
    if (!(extension = strrchr(filename, '.')) || strcmp(extension, ".gz") != 0) {
#endif
      if ((extension = strrchr(filename, '.')) && ((strcmp(extension, ".lzma") == 0) || (strcmp(extension, ".xz") == 0))) {
        SDDS_dataset->layout.lzmaFile = 1;
        if (!(SDDS_dataset->layout.lzmafp = UnpackLZMAOpen(filename))) {
          sprintf(s, "Unable to open file \"%s\" for reading (SDDS_InitializeInput)", filename);
          SDDS_SetError(s);
          return (0);
        }
        SDDS_dataset->layout.fp = SDDS_dataset->layout.lzmafp->fp;
      } else {
        if (!(SDDS_dataset->layout.fp = UnpackFopen(filename, UNPACK_REQUIRE_SDDS | UNPACK_USE_PIPE, &SDDS_dataset->layout.popenUsed, NULL))) {
          sprintf(s, "Unable to open file \"%s\" for reading (SDDS_InitializeInput)", filename);
          SDDS_SetError(s);
          return (0);
        }
      }
#if defined(zLib)
    } else {
      SDDS_dataset->layout.gzipFile = 1;
      if (!(SDDS_dataset->layout.gzfp = gzopen(filename, "rb"))) {
        sprintf(s, "Unable to open file \"%s\" for reading (SDDS_InitializeInput)", filename);
        SDDS_SetError(s);
        return (0);
      }
    }
#endif
  }
  SDDS_dataset->page_number = SDDS_dataset->page_started = 0;
  SDDS_dataset->file_had_data = 0;
  SDDS_DeferSavingLayout(SDDS_dataset, 1);
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!SDDS_GZipReadLayout(SDDS_dataset, SDDS_dataset->layout.gzfp))
      return (0);
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!SDDS_LZMAReadLayout(SDDS_dataset, SDDS_dataset->layout.lzmafp))
        return (0);
    } else {
      if (!SDDS_ReadLayout(SDDS_dataset, SDDS_dataset->layout.fp))
        return (0);
    }
#if defined(zLib)
  }
#endif
  SDDS_dataset->layout.layout_written = 0;
  SDDS_DeferSavingLayout(SDDS_dataset, 0);
  if (!SDDS_SaveLayout(SDDS_dataset))
    return 0;
  if (SDDS_dataset->layout.n_columns &&
      ((!(SDDS_dataset->column_flag = (int32_t *)SDDS_Malloc(sizeof(int32_t) * SDDS_dataset->layout.n_columns)) ||
        !(SDDS_dataset->column_order = (int32_t *)SDDS_Malloc(sizeof(int32_t) * SDDS_dataset->layout.n_columns))) ||
       (!SDDS_SetMemory(SDDS_dataset->column_flag, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)1, (int32_t)0) ||
        !SDDS_SetMemory(SDDS_dataset->column_order, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)0, (int32_t)1)))) {
    SDDS_SetError("Unable to initialize input--memory allocation failure (SDDS_InitializeInput)");
    return (0);
  }
  SDDS_dataset->mode = SDDS_READMODE; /*reading */
  SDDS_dataset->pagecount_offset = NULL;
  if (!SDDS_dataset->layout.gzipFile && !SDDS_dataset->layout.lzmaFile && !SDDS_dataset->layout.popenUsed && SDDS_dataset->layout.filename) {
    /* Data is not:
         1. from a gzip file
         2. from a file that is being internally decompressed by a command executed with popen()
         3. from a pipe set up externally (e.g., -pipe=in on commandline)
      */
    SDDS_dataset->pages_read = 0;
    SDDS_dataset->pagecount_offset = malloc(sizeof(*SDDS_dataset->pagecount_offset));
    SDDS_dataset->pagecount_offset[0] = ftell(SDDS_dataset->layout.fp);
    fseek(SDDS_dataset->layout.fp, 0, 2); /*point to the end of the file */
    SDDS_dataset->endOfFile_offset = ftell(SDDS_dataset->layout.fp);
    fseek(SDDS_dataset->layout.fp, SDDS_dataset->pagecount_offset[0], 0);
    /*point to the beginning of the first page */
  }
  return (1);
}

SDDS_InitializeInputFromSearchPath()

epicsShareFuncSDDS int32_t SDDS_InitializeInputFromSearchPath ( SDDS_DATASET * SDDSin, char * file )

extern

Initializes the SDDS_DATASET structure for input from the search path.

The search path is defined by calling setSearchPath. This function attempts to find the file in the search path and initializes the SDDS dataset for input.

Parameters

SDDSin	The SDDS_DATASET structure to be initialized.
file	The name of the file to be opened for input.

Returns

1 on success, 0 on failure.

Definition at line 1811 of file SDDS_input.c.

                                                                             {
  char *filename;
  int32_t value;
  if (!(filename = findFileInSearchPath(file))) {
    char *s;
    if (!(s = SDDS_Malloc(sizeof(*s) * (strlen(file) + 100))))
      SDDS_SetError("file does not exist in search path (InitializeInputFromSearchPath)");
    else {
      sprintf(s, "file %s does not exist in search path (InitializeInputFromSearchPath)", file);
      SDDS_SetError(s);
      free(s);
    }
    return 0;
  }
  value = SDDS_InitializeInput(SDDSin, filename);
  free(filename);
  return value;
}

SDDS_InitializeOutput()

epicsShareFuncSDDS int32_t SDDS_InitializeOutput ( SDDS_DATASET * SDDS_dataset, int32_t data_mode, int32_t lines_per_row, const char * description, const char * contents, const char * filename )

extern

Initializes the SDDS output dataset.

This function sets up the SDDS dataset for output operations by initializing the necessary structures, configuring the data mode (ASCII, Binary, or Parallel), handling file opening (including compressed files), and setting dataset metadata such as description and contents. It ensures that the dataset is ready for writing data according to the specified parameters.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be initialized for output.
[in]	data_mode	The data mode for the output dataset. Acceptable values are: SDDS_ASCII: ASCII text format. SDDS_BINARY: Binary format. SDDS_PARALLEL: Parallel processing mode.
[in]	lines_per_row	The number of lines per row in the output dataset. This parameter is used only for ASCII output and is typically set to 1.
[in]	description	A string containing the description of the output dataset. Pass NULL if no description is desired.
[in]	contents	A string detailing the contents of the output dataset. Pass NULL if no contents are desired.
[in]	filename	The name of the file to which the dataset will be written. If NULL, the dataset will be written to standard output.

Returns

• 1 on successful initialization.
• 0 if an error occurred during initialization. In this case, an error message is set internally.

Precondition

• The SDDS_dataset pointer must be valid and point to a properly allocated SDDS_DATASET structure.

Postcondition

• The dataset is configured for output according to the specified parameters.
• The output file is opened and locked if a filename is provided.
• The dataset's internal state reflects the initialization status.

Note

• When using compressed file formats (e.g., .gz, .lzma, .xz), the output mode is forced to binary.
• Environment variable SDDS_OUTPUT_ENDIANESS can be set to "big" or "little" to declare the byte order.
• For ASCII output, ensure that lines_per_row is set appropriately to match the data structure.

Warning

• Appending to compressed files is not supported and will result in an error.
• Ensure that the specified file is not locked by another process to avoid initialization failures.
• Changing data mode after initialization is not supported and may lead to undefined behavior.

Definition at line 602 of file SDDS_output.c.

                                                                                                                                                                         {
  char s[SDDS_MAXLINE];
  char *extension;
  char *outputEndianess = NULL;
 
  if (data_mode == SDDS_PARALLEL)
    return SDDS_Parallel_InitializeOutput(SDDS_dataset, description, contents, filename);
 
  if (sizeof(gzFile) != sizeof(void *)) {
    SDDS_SetError("gzFile is not the same size as void *, possible corruption of the SDDS_LAYOUT structure");
    return (0);
  }
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_InitializeOutput"))
    return 0;
  if (!SDDS_ZeroMemory((void *)SDDS_dataset, sizeof(SDDS_DATASET))) {
    sprintf(s, "Unable to initialize output for file %s--can't zero SDDS_DATASET structure (SDDS_InitializeOutput)", filename);
    SDDS_SetError(s);
    return 0;
  }
  SDDS_dataset->layout.popenUsed = SDDS_dataset->layout.gzipFile = SDDS_dataset->layout.lzmaFile = SDDS_dataset->layout.disconnected = 0;
  SDDS_dataset->layout.depth = SDDS_dataset->layout.data_command_seen = SDDS_dataset->layout.commentFlags = SDDS_dataset->deferSavingLayout = 0;
  if (!filename) {
#if defined(_WIN32)
    if (_setmode(_fileno(stdout), _O_BINARY) == -1) {
      sprintf(s, "unable to set stdout to binary mode");
      SDDS_SetError(s);
      return 0;
    }
#endif
    SDDS_dataset->layout.fp = stdout;
  } else {
    if (SDDS_FileIsLocked(filename)) {
      sprintf(s, "unable to open file %s for writing--file is locked (SDDS_InitializeOutput)", filename);
      SDDS_SetError(s);
      return 0;
    }
    if ((extension = strrchr(filename, '.')) && ((strcmp(extension, ".xz") == 0) || (strcmp(extension, ".lzma") == 0))) {
      SDDS_dataset->layout.lzmaFile = 1;
      data_mode = SDDS_BINARY; /* force binary mode for output lzma files. The reading of ascii lzma files is flaky because of the lzma_gets command, plus the output files will be much smaller */
      if (!(SDDS_dataset->layout.lzmafp = lzma_open(filename, FOPEN_WRITE_MODE))) {
        sprintf(s, "Unable to open file %s for writing (SDDS_InitializeOutput)", filename);
        SDDS_SetError(s);
        return 0;
      }
      SDDS_dataset->layout.fp = SDDS_dataset->layout.lzmafp->fp;
    } else {
      if (!(SDDS_dataset->layout.fp = fopen(filename, FOPEN_WRITE_MODE))) {
        sprintf(s, "Unable to open file %s for writing (SDDS_InitializeOutput)", filename);
        SDDS_SetError(s);
        return 0;
      }
    }
    if (!SDDS_LockFile(SDDS_dataset->layout.fp, filename, "SDDS_InitializeOutput"))
      return 0;
#if defined(zLib)
    if ((extension = strrchr(filename, '.')) && (strcmp(extension, ".gz") == 0)) {
      SDDS_dataset->layout.gzipFile = 1;
      if ((SDDS_dataset->layout.gzfp = gzdopen(fileno(SDDS_dataset->layout.fp), FOPEN_WRITE_MODE)) == NULL) {
        sprintf(s, "Unable to open compressed file %s for writing (SDDS_InitializeOutput)", filename);
        SDDS_SetError(s);
        return 0;
      }
    }
#endif
  }
  SDDS_dataset->page_number = SDDS_dataset->page_started = 0;
  SDDS_dataset->file_had_data = SDDS_dataset->layout.layout_written = 0;
  if (!filename)
    SDDS_dataset->layout.filename = NULL;
  else if (!SDDS_CopyString(&SDDS_dataset->layout.filename, filename)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeOutput)", filename);
    SDDS_SetError(s);
    return 0;
  }
  if ((outputEndianess = getenv("SDDS_OUTPUT_ENDIANESS"))) {
    if (strncmp(outputEndianess, "big", 3) == 0)
      SDDS_dataset->layout.byteOrderDeclared = SDDS_BIGENDIAN;
    else if (strncmp(outputEndianess, "little", 6) == 0)
      SDDS_dataset->layout.byteOrderDeclared = SDDS_LITTLEENDIAN;
  } else {
    SDDS_dataset->layout.byteOrderDeclared = SDDS_IsBigEndianMachine() ? SDDS_BIGENDIAN : SDDS_LITTLEENDIAN;
  }
 
  if (data_mode < 0 || data_mode > SDDS_NUM_DATA_MODES) {
    sprintf(s, "Invalid data mode for file %s (SDDS_InitializeOutput)", filename ? filename : "stdout");
    SDDS_SetError(s);
    return 0;
  }
  if (data_mode == SDDS_ASCII && lines_per_row <= 0) {
    sprintf(s, "Invalid number of lines per row for file %s (SDDS_InitializeOutput)", filename ? filename : "stdout");
    SDDS_SetError(s);
    return 0;
  }
  SDDS_dataset->layout.version = SDDS_VERSION;
  SDDS_dataset->layout.data_mode.mode = data_mode;
  SDDS_dataset->layout.data_mode.lines_per_row = lines_per_row;
  SDDS_dataset->layout.data_mode.no_row_counts = 0;
  SDDS_dataset->layout.data_mode.fixed_row_count = 0;
  SDDS_dataset->layout.data_mode.fsync_data = 0;
  SDDS_dataset->layout.data_mode.column_memory_mode = DEFAULT_COLUMN_MEMORY_MODE;
  /*This is only temporary, soon the default will be column major order */
  SDDS_dataset->layout.data_mode.column_major = 0;
  if (description && !SDDS_CopyString(&SDDS_dataset->layout.description, description)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeOutput)", filename ? filename : "stdout");
    SDDS_SetError(s);
    return 0;
  }
  if (contents && !SDDS_CopyString(&SDDS_dataset->layout.contents, contents)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeOutput)", filename ? filename : "stdout");
    SDDS_SetError(s);
    return 0;
  }
  SDDS_dataset->mode = SDDS_WRITEMODE; /*writing */
  SDDS_dataset->pagecount_offset = NULL;
  SDDS_dataset->parallel_io = 0;
  return (1);
}

SDDS_InterpretEscapes()

epicsShareFuncSDDS void SDDS_InterpretEscapes ( char * s )

extern

Interprets and converts escape sequences in a string.

This function processes a string containing escape sequences and converts them into their corresponding character representations. Supported escape sequences include:

• Standard ANSI escape codes: \n, \t, \b, \r, \f, \v, \\, \', \", \a, \?
• Octal values: \ddd
• SDDS-specific escape codes: \!, \)

The function modifies the input string s in place, replacing escape sequences with their actual character values.

Parameters

[in,out]

s

Pointer to the null-terminated string to be processed. The string will be modified in place.

Note

• Ensure that the input string s has sufficient buffer space to accommodate the modified characters, especially when dealing with octal escape sequences that may reduce the overall string length.

Warning

• The function does not perform bounds checking. Ensure that the input string is properly null-terminated to prevent undefined behavior.
• Unrecognized escape sequences (other than the ones specified) will result in the backslash being retained in the string.

See also

SDDS_EscapeNewlines, SDDS_UnescapeNewlines

Definition at line 5173 of file SDDS_utils.c.

{
  char *ptr;
  int32_t count;
 
  ptr = s;
  while (*s) {
    if (*s != '\\')
      *ptr++ = *s++;
    else {
      s++;
      if (!*s) {
        *ptr++ = '\\';
        *ptr++ = 0;
        return;
      }
      switch (*s) {
      case 'n':
        *ptr++ = '\n';
        s++;
        break;
      case 't':
        *ptr++ = '\t';
        s++;
        break;
      case 'b':
        *ptr++ = '\b';
        s++;
        break;
      case 'r':
        *ptr++ = '\r';
        s++;
        break;
      case 'f':
        *ptr++ = '\f';
        s++;
        break;
      case 'v':
        *ptr++ = '\v';
        s++;
        break;
      case '\\':
        *ptr++ = '\\';
        s++;
        break;
      case '\'':
        *ptr++ = '\'';
        s++;
        break;
      case '"':
        *ptr++ = '\"';
        s++;
        break;
      case 'a':
        *ptr++ = '\a';
        s++;
        break;
      case '?':
        *ptr++ = '\?';
        s++;
        break;
      case '!':
        *ptr++ = '!';
        s++;
        break;
      default:
        if (*s >= '0' && *s <= '9') {
          *ptr = 0;
          count = 0;
          while (++count <= 3 && *s >= '0' && *s <= '9')
            *ptr = 8 * (*ptr) + *s++ - '0';
          ptr++;
        } else {
          *ptr++ = '\\';
        }
        break;
      }
    }
  }
  *ptr = 0;
}

SDDS_IsActive()

epicsShareFuncSDDS int32_t SDDS_IsActive ( SDDS_DATASET * SDDS_dataset )

extern

Checks whether an SDDS dataset is currently active.

This function determines the active status of the provided SDDS dataset by verifying if its file pointer is non-NULL.

Parameters

[in]

SDDS_dataset

Pointer to the SDDS_DATASET structure to be checked.

Returns

• 1 if the dataset is active (i.e., the file pointer is non-NULL).
• 0 if the dataset is inactive (i.e., the file pointer is NULL).
• -1 if a NULL pointer is passed, indicating an error.

Note

An inactive dataset does not have an associated open file, and certain operations may not be applicable.

See also

SDDS_ForceInactive, SDDS_SetError

Definition at line 3325 of file SDDS_utils.c.

                                                  {
  if (!SDDS_dataset) {
    SDDS_SetError("NULL SDDS_DATASET passed (SDDS_IsActive)");
    return (-1);
  }
  if (!SDDS_dataset->layout.fp)
    return (0);
  return (1);
}

SDDS_IsBigEndianMachine()

epicsShareFuncSDDS int32_t SDDS_IsBigEndianMachine ( )

extern

Determines whether the current machine uses big-endian byte ordering.

This function checks the byte order of the machine on which the program is running. It returns 1 if the machine is big-endian and 0 if it is little-endian.

Returns

• 1 if the machine is big-endian.
• 0 if the machine is little-endian.

Note

• Endianness detection is based on inspecting the byte order of an integer value.

Warning

• This function assumes that int32_t is 4 bytes in size. If compiled on a system where int32_t differs in size, the behavior may be incorrect.

See also

SDDS_SetDataMode

Definition at line 5374 of file SDDS_utils.c.

                                  {
  int32_t x = 1;
  if (*((char *)&x))
    return 0;
  return 1;
}

SDDS_IsQuoted()

epicsShareFuncSDDS int32_t SDDS_IsQuoted ( char * string, char * position, char quotation_mark )

extern

Checks if a position in a string is within a quoted section.

Determines whether the specified position within a string falls inside a quoted section delimited by the given quotation mark.

Parameters

string	The string to examine.
position	The position within the string to check.
quotation_mark	The character used as the quotation mark.

Returns

Returns 1 if the position is within a quoted section, 0 otherwise.

Definition at line 218 of file SDDS_input.c.

                                                                         {
  int32_t in_quoted_section;
  char *string0;
 
  if (*position == quotation_mark)
    return (1);
 
  in_quoted_section = 0;
  string0 = string;
  while (*string) {
    if (*string == quotation_mark && (string == string0 || *(string - 1) != '\\'))
      in_quoted_section = !in_quoted_section;
    else if (string == position)
      return (in_quoted_section);
    string++;
  }
  return (0);
}

SDDS_IsValidName()

epicsShareFuncSDDS int32_t SDDS_IsValidName ( const char * name, const char * class )

extern

Checks if a given name is valid for a specified class within the SDDS dataset.

This function validates whether the provided name adheres to the naming conventions and rules defined by the current name validity flags for the specified class (e.g., parameter, column). It ensures that the name contains only allowed characters and follows the required structure.

Parameters

[in]	name	The name to be validated. Must be a NULL-terminated string.
[in]	class	The class type to which the name belongs (e.g., "parameter", "column"). This is used primarily for error reporting.

Returns

• 1 if the name is valid for the specified class.
• 0 if the name is invalid, with an error message set internally.

Precondition

• The name must be a valid NULL-terminated string.
• The class must be a valid NULL-terminated string representing a recognized class type.

Postcondition

• If the name is invalid, an error message is recorded detailing the reason.

Note

• The validation rules are influenced by the current name validity flags set via SDDS_SetNameValidityFlags.
• Environment variables or other configuration settings may also affect name validity.

Warning

• Using names that do not adhere to the validation rules will result in parameters or columns not being defined.
• Ensure that all names meet the required standards before attempting to define dataset elements.

Definition at line 2099 of file SDDS_output.c.

                                                              {
  char *ptr;
  int32_t isValid = 1;
  char s[SDDS_MAXLINE];
  static const char *const validChars = "@:#+%-._$&/[]";
  static const char *const startChars = ".:";
  uint32_t flags = SDDS_GetLockedNameValidityFlags();
 
  if (flags & SDDS_ALLOW_ANY_NAME)
    return 1;
  ptr = (char *)name;
  if (strlen(name) == 0)
    isValid = 0;
  else if (!(flags & SDDS_ALLOW_V15_NAME)) {
    /* post V1.5 allows only alpha and startChars members as first character */
    /* V1.5 allows alpha, digits, and any validChars members */
    if (!(isalpha(*ptr) || strchr(startChars, *ptr)))
      isValid = 0;
  }
  while (isValid && *ptr) {
    if (!(isalnum(*ptr) || strchr(validChars, *ptr)))
      isValid = 0;
    ptr++;
  }
  if (!isValid) {
    sprintf(s, "The following %s name is invalid: >%s<\n(sddsconvert may be used to change the name)\n", class, name);
    SDDS_SetError(s);
    return 0;
  }
  return 1;
}

SDDS_ItemInsideWindow()

epicsShareFuncSDDS int32_t SDDS_ItemInsideWindow ( void * data, int64_t index, int32_t type, double lower_limit, double upper_limit )

extern

Checks whether a data item is within a specified numeric window.

This function determines if the data item at the given index within the data array falls within the range defined by lower_limit and upper_limit. It handles various numeric data types and ensures that the value is neither NaN nor infinity.

Parameters

data	Pointer to the data array.
index	The index of the item within the data array to be checked.
type	The data type of the item. Supported types include: SDDS_SHORT SDDS_USHORT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_FLOAT SDDS_DOUBLE SDDS_LONGDOUBLE
lower_limit	The lower bound of the numeric window.
upper_limit	The upper bound of the numeric window.

Returns

Returns 1 if the item is within the window and valid, otherwise returns 0.

Return values

1	Indicates that the item is within the specified numeric window and is a valid number.
0	Indicates that the item is outside the specified window, is NaN, is infinite, or the data type is non-numeric.

Note

• The function sets an error message if the data type is non-numeric.
• It is essential to ensure that the data array is properly initialized and contains valid data before calling this function.

See also

SDDS_FilterRowsOfInterest, SDDS_GetParameterAsDouble

Definition at line 4078 of file SDDS_extract.c.

                                                                                                               {
  short short_val;
  unsigned short ushort_val;
  int32_t long_val;
  uint32_t ulong_val;
  int64_t long64_val;
  uint64_t ulong64_val;
  long double ldouble_val;
  double double_val;
  float float_val;
 
  switch (type) {
  case SDDS_SHORT:
    if ((short_val = *((short *)data + index)) < lower_limit || short_val > upper_limit)
      return (0);
    return (1);
  case SDDS_USHORT:
    if ((ushort_val = *((unsigned short *)data + index)) < lower_limit || ushort_val > upper_limit)
      return (0);
    return (1);
  case SDDS_LONG:
    if ((long_val = *((int32_t *)data + index)) < lower_limit || long_val > upper_limit)
      return (0);
    return (1);
  case SDDS_ULONG:
    if ((ulong_val = *((uint32_t *)data + index)) < lower_limit || ulong_val > upper_limit)
      return (0);
    return (1);
  case SDDS_LONG64:
    if ((long64_val = *((int64_t *)data + index)) < lower_limit || long64_val > upper_limit)
      return (0);
    return (1);
  case SDDS_ULONG64:
    if ((ulong64_val = *((uint64_t *)data + index)) < lower_limit || ulong64_val > upper_limit)
      return (0);
    return (1);
  case SDDS_FLOAT:
    if ((float_val = *((float *)data + index)) < lower_limit || float_val > upper_limit)
      return (0);
    if (isnan(float_val) || isinf(float_val))
      return 0;
    return (1);
  case SDDS_DOUBLE:
    if ((double_val = *((double *)data + index)) < lower_limit || double_val > upper_limit)
      return 0;
    if (isnan(double_val) || isinf(double_val))
      return 0;
    return (1);
  case SDDS_LONGDOUBLE:
    if ((ldouble_val = *((long double *)data + index)) < lower_limit || ldouble_val > upper_limit)
      return 0;
    if (isnan(ldouble_val) || isinf(ldouble_val))
      return 0;
    return (1);
  default:
    SDDS_SetError("Unable to complete window check--item type is non-numeric (SDDS_ItemInsideWindow)");
    return (0);
  }
}

SDDS_LengthenTable()

epicsShareFuncSDDS int32_t SDDS_LengthenTable ( SDDS_DATASET * SDDS_dataset, int64_t n_additional_rows )

extern

Increases the number of allocated rows in the SDDS dataset's data table.

This function extends the allocated memory for the data table in the specified SDDS dataset by adding the specified number of additional rows. It reallocates memory for each column's data array and the row flags, initializing the newly allocated memory to zero.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure whose table will be lengthened.
n_additional_rows	The number of additional rows to allocate. If n_additional_rows is less than zero, it is treated as zero.

Returns

Returns 1 on successful reallocation and initialization. On failure, returns 0 and records an error message.

See also

SDDS_Realloc, SDDS_SetMemory, SDDS_ZeroMemory, SDDS_SetError

Definition at line 303 of file SDDS_dataprep.c.

                                                                                  {
  SDDS_LAYOUT *layout;
  int64_t i, size;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_LengthenTable"))
    return (0);
  layout = &SDDS_dataset->layout;
#if defined(DEBUG)
  fprintf(stderr, "table size being increased from %" PRId64 " to %" PRId64 " rows\n", SDDS_dataset->n_rows_allocated, SDDS_dataset->n_rows_allocated + n_additional_rows);
#endif
  if (!SDDS_dataset->data && !(SDDS_dataset->data = (void **)calloc(layout->n_columns, sizeof(*SDDS_dataset->data)))) {
    SDDS_SetError("Unable to start page--memory allocation failure1 (SDDS_LengthenTable)");
    return (0);
  }
  if (n_additional_rows < 0)
    n_additional_rows = 0;
  for (i = 0; i < layout->n_columns; i++) {
    size = SDDS_type_size[layout->column_definition[i].type - 1];
    if (!(SDDS_dataset->data[i] = (void *)SDDS_Realloc(SDDS_dataset->data[i], (SDDS_dataset->n_rows_allocated + n_additional_rows) * size))) {
      SDDS_SetError("Unable to lengthen page--memory allocation failure2 (SDDS_LengthenTable)");
      return (0);
    }
    SDDS_ZeroMemory((char *)SDDS_dataset->data[i] + size * SDDS_dataset->n_rows_allocated, size * n_additional_rows);
  }
  if (!(SDDS_dataset->row_flag = (int32_t *)SDDS_Realloc(SDDS_dataset->row_flag, (SDDS_dataset->n_rows_allocated + n_additional_rows) * sizeof(int32_t)))) {
    SDDS_SetError("Unable to lengthen page--memory allocation failure3 (SDDS_LengthenTable)");
    return (0);
  }
  SDDS_dataset->n_rows_allocated += n_additional_rows;
 
  if (!SDDS_SetMemory(SDDS_dataset->row_flag, SDDS_dataset->n_rows_allocated, SDDS_LONG, (int32_t)1, (int32_t)0) ||
      !SDDS_SetMemory(SDDS_dataset->column_flag, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)1, (int32_t)0) || 
      !SDDS_SetMemory(SDDS_dataset->column_order, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)0, (int32_t)1)) {
    SDDS_SetError("Unable to lengthen page--memory initialization failure4 (SDDS_LengthenTable)");
    return (0);
  }
  return (1);
}

SDDS_LockFile()

epicsShareFuncSDDS int32_t SDDS_LockFile ( FILE * fp, const char * filename, const char * caller )

extern

Attempts to lock a specified file.

This function tries to acquire a lock on the provided file using the given file pointer. If file locking is enabled via the F_TEST and ALLOW_FILE_LOCKING macros, it first tests whether the file can be locked and then attempts to establish an exclusive lock. If locking fails at any step, an error message is set, and the function returns 0.

If file locking is not enabled, the function assumes that the file is not locked and returns 1.

Parameters

[in]	fp	Pointer to the open FILE stream associated with the file to be locked.
[in]	filename	The path to the file to be locked. Used primarily for error messaging.
[in]	caller	A string identifying the caller or the context in which the lock is being attempted. This is used in error messages to provide more information about the lock attempt.

Returns

• 1 if the file lock is successfully acquired or if file locking is not enabled.
• 0 if the file is already locked or if locking fails for another reason.

Note

The function relies on the lockf system call for file locking, which may not be supported on all platforms.

Warning

Proper error handling should be implemented by the caller to handle cases where file locking fails.

See also

SDDS_FileIsLocked, SDDS_SetError

Definition at line 3401 of file SDDS_utils.c.

                                                                          {
#if defined(F_TEST) && ALLOW_FILE_LOCKING
  char s[1024];
  if (lockf(fileno(fp), F_TEST, 0) == -1) {
    sprintf(s, "Unable to access file %s--file is locked (%s)", filename, caller);
    SDDS_SetError(s);
    return 0;
  }
  if (lockf(fileno(fp), F_TLOCK, 0) == -1) {
    sprintf(s, "Unable to establish lock on file %s (%s)", filename, caller);
    SDDS_SetError(s);
    return 0;
  }
  return 1;
#else
  return 1;
#endif
}

SDDS_Logic()

epicsShareFuncSDDS int32_t SDDS_Logic ( int32_t previous, int32_t match, uint32_t logic )

extern

Applies logical operations to determine the new state of a row flag based on previous and current match conditions.

This function evaluates logical conditions between a previous flag (previous) and a current match flag (match) based on the provided logic flags. It supports various logical operations such as AND, OR, negation of previous flags, and negation of match results.

Parameters

previous	The previous state of the row flag (typically 0 or 1).
match	The current match result to be combined with the previous flag.
logic	An unsigned integer representing logical operation flags. Supported flags include: SDDS_0_PREVIOUS: Set the previous flag to 0. SDDS_1_PREVIOUS: Set the previous flag to 1. SDDS_NEGATE_PREVIOUS: Negate the previous flag. SDDS_NEGATE_MATCH: Negate the current match result. SDDS_AND: Perform a logical AND between the previous flag and the match result. SDDS_OR: Perform a logical OR between the previous flag and the match result. SDDS_NEGATE_EXPRESSION: Negate the final logical expression result.

Returns

Returns the result of the logical operation as an integer (0 or 1).

Return values

1	Indicates that the final logical condition evaluates to true.
0	Indicates that the final logical condition evaluates to false.

Note

• Multiple logic flags can be combined using bitwise OR to perform complex logical operations.
• The order of operations follows the precedence defined within the function implementation.

See also

SDDS_SetRowsOfInterest, SDDS_MatchRowsOfInterest

Definition at line 4166 of file SDDS_extract.c.

                                                                    {
  if (logic & SDDS_0_PREVIOUS)
    previous = 0;
  else if (logic & SDDS_1_PREVIOUS)
    previous = 1;
  if (logic & SDDS_NEGATE_PREVIOUS)
    previous = !previous;
  if (logic & SDDS_NEGATE_MATCH)
    match = !match;
  if (logic & SDDS_AND)
    match = match && previous;
  else if (logic & SDDS_OR)
    match = match || previous;
  else
    match = previous;
  if (logic & SDDS_NEGATE_EXPRESSION)
    match = !match;
  return (match);
}

SDDS_MakePointerArray()

epicsShareFuncSDDS void * SDDS_MakePointerArray ( void * data, int32_t type, int32_t dimensions, int32_t * dimension )

extern

Creates a multi-dimensional pointer array from a contiguous data block.

This function generates a multi-dimensional pointer array that maps to a contiguous block of data. It supports arrays with multiple dimensions by recursively creating pointer layers. The dimensions parameter specifies the number of dimensions, and the dimension array provides the size for each dimension.

Parameters

[in]	data	Pointer to the contiguous data block to be mapped.
[in]	type	The SDDS data type of the elements in the data block. Must be one of the SDDS type constants: SDDS_SHORT SDDS_USHORT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_FLOAT SDDS_DOUBLE SDDS_LONGDOUBLE SDDS_CHARACTER
[in]	dimensions	The number of dimensions for the pointer array.
[in]	dimension	An array specifying the size of each dimension.

Returns

• Returns a pointer to the newly created multi-dimensional pointer array on success.
• Returns NULL if the input data is NULL, the dimension array is invalid, the type is unknown, or memory allocation fails.

Note

• The function uses SDDS_MakePointerArrayRecursively to handle multi-dimensional allocations.
• The caller is responsible for freeing the allocated pointer array using SDDS_FreePointerArray.

See also

SDDS_MakePointerArrayRecursively

SDDS_FreePointerArray

SDDS_SetError

Definition at line 3046 of file SDDS_utils.c.

                                                                                              {
  int32_t i;
 
  if (!data) {
    SDDS_SetError("Unable to make pointer array--NULL data array (SDDS_MakePointerArray)");
    return (NULL);
  }
  if (!dimension || !dimensions) {
    SDDS_SetError("Unable to make pointer array--NULL or zero-length dimension array (SDDS_MakePointerArray)");
    return (NULL);
  }
  if (type <= 0 || type > SDDS_NUM_TYPES) {
    SDDS_SetError("Unable to make pointer array--unknown data type (SDDS_MakePointerArray)");
    return (NULL);
  }
  for (i = 0; i < dimensions; i++)
    if (dimension[i] <= 0) {
      SDDS_SetError("Unable to make pointer array--number of elements invalid (SDDS_MakePointerArray)");
      return (NULL);
    }
  if (dimensions == 1)
    return (data);
  return (SDDS_MakePointerArrayRecursively(data, SDDS_type_size[type - 1], dimensions, dimension));
}

SDDS_Malloc()

epicsShareFuncSDDS void * SDDS_Malloc ( size_t size )

extern

Allocates memory of a specified size.

This function is a wrapper around the standard malloc function, used by SDDS routines to allocate memory. It ensures that a minimum allocation size is enforced.

Parameters

[in]

size

Number of bytes to allocate.

Returns

Pointer to the allocated memory. If size is less than or equal to zero, it allocates memory for 4 bytes by default. Returns NULL if memory allocation fails.

Note

Users should always check the returned pointer for NULL before using it.

See also

SDDS_Calloc

SDDS_Free

Definition at line 705 of file SDDS_utils.c.

                               {
  if (size <= 0)
    size = 4;
  return malloc(size);
}

SDDS_MatchArrays()

epicsShareFuncSDDS int32_t SDDS_MatchArrays ( SDDS_DATASET * SDDS_dataset, char *** nameReturn, int32_t matchMode, int32_t typeMode, ... )

extern

Matches and retrieves array names from an SDDS dataset based on specified criteria.

This function selects arrays from the provided SDDS dataset according to the specified matching mode and type mode. It supports various calling conventions depending on the matching criteria.

The function supports the following matching modes:

• SDDS_NAME_ARRAY:
  • Parameters: int32_t n_entries, char **name
  • Description: Matches arrays whose names are present in the provided array.
• SDDS_NAMES_STRING:
  • Parameters: char *names
  • Description: Matches arrays whose names are specified in a single comma-separated string.
• SDDS_NAME_STRINGS:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Matches arrays whose names are specified as individual string arguments, terminated by a NULL pointer.
• SDDS_MATCH_STRING:
  • Parameters: char *name, int32_t logic_mode
  • Description: Matches arrays based on a wildcard pattern provided in name, using the specified logical mode.
• SDDS_MATCH_EXCLUDE_STRING:
  • Parameters: char *name, char *exclude, int32_t logic_mode
  • Description: Matches arrays based on a wildcard pattern provided in name, excluding those that match the exclude pattern, using the specified logical mode.

Additionally, the typeMode parameter allows filtering based on array types, such as numeric, floating, or integer types.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure containing the dataset.
[out]	nameReturn	Pointer to a char** that will be allocated and populated with the names of the matched arrays. The caller is responsible for freeing the allocated memory.
[in]	matchMode	Specifies the matching mode (e.g., SDDS_NAME_ARRAY, SDDS_NAMES_STRING, etc.).
[in]	typeMode	Specifies the type matching mode (e.g., FIND_SPECIFIED_TYPE, FIND_NUMERIC_TYPE, FIND_FLOATING_TYPE, FIND_INTEGER_TYPE).
[in]	...	Variable arguments depending on matchMode: SDDS_NAME_ARRAY: int32_t n_entries, char **name SDDS_NAMES_STRING: char *names SDDS_NAME_STRINGS: char *name1, char *name2, ..., NULL SDDS_MATCH_STRING: char *name, int32_t logic_mode SDDS_MATCH_EXCLUDE_STRING: char *name, char *exclude, int32_t logic_mode

Returns

• Returns the number of matched arrays on success.
• Returns -1 if an error occurs (e.g., invalid parameters, memory allocation failure).

Note

• The function internally manages memory for the matching process and allocates memory for nameReturn, which must be freed by the caller using appropriate memory deallocation functions.
• The dataset must be properly initialized and contain a valid layout before calling this function.

Warning

• Ensure that the variable arguments match the expected parameters for the specified matchMode.
• The caller is responsible for freeing the memory allocated for nameReturn to avoid memory leaks.

See also

SDDS_MatchColumns, SDDS_MatchParameters, SDDS_SetError

Definition at line 4121 of file SDDS_utils.c.

{
  static MDB_THREAD_LOCAL int32_t flags = 0, *flag = NULL;
  char **name, *string, *match_string, *ptr, *exclude_string;
  va_list argptr;
  int32_t i, j, index, n_names, retval, requiredType, matches;
  /*  int32_t type; */
  int32_t local_memory; /* (0,1,2) --> (none, pointer array, pointer array + strings) locally allocated */
  char buffer[SDDS_MAXLINE];
  int32_t logic;
 
  name = NULL;
  match_string = exclude_string = NULL;
  n_names = requiredType = local_memory = logic = 0;
 
  matches = -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_MatchArrays"))
    return -1;
  if (nameReturn)
    *nameReturn = NULL;
 
  retval = 1;
  va_start(argptr, typeMode);
  if (typeMode == FIND_SPECIFIED_TYPE)
    requiredType = va_arg(argptr, int32_t);
  switch (matchMode) {
  case SDDS_NAME_ARRAY:
    local_memory = 0;
    n_names = va_arg(argptr, int32_t);
    name = va_arg(argptr, char **);
    break;
  case SDDS_NAMES_STRING:
    local_memory = 2;
    n_names = 0;
    name = NULL;
    ptr = va_arg(argptr, char *);
    SDDS_CopyString(&string, ptr);
    while ((ptr = strchr(string, ',')))
      *ptr = ' ';
    while ((SDDS_GetToken(string, buffer, SDDS_MAXLINE) > 0)) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1))) || !SDDS_CopyString(name + n_names, buffer)) {
        SDDS_SetError("Unable to process array selection--memory allocation failure (SDDS_MatchArrays)");
        retval = 0;
        break;
      }
      n_names++;
    }
    free(string);
    break;
  case SDDS_NAME_STRINGS:
    local_memory = 1;
    n_names = 0;
    name = NULL;
    while ((string = va_arg(argptr, char *))) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1)))) {
        SDDS_SetError("Unable to process array selection--memory allocation failure (SDDS_MatchArrays)");
        retval = 0;
        break;
      }
      name[n_names++] = string;
    }
    break;
  case SDDS_MATCH_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process array selection--invalid matching string (SDDS_MatchArrays)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  case SDDS_MATCH_EXCLUDE_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process array selection--invalid matching string (SDDS_MatchArrays)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process array exclusion--invalid matching string (SDDS_MatchArrays)");
      retval = 0;
      break;
    }
    exclude_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  default:
    SDDS_SetError("Unable to process array selection--unknown match mode (SDDS_MatchArrays)");
    retval = 0;
    break;
  }
  va_end(argptr);
  if (retval == 0)
    return -1;
 
  if (n_names == 0) {
    SDDS_SetError("Unable to process array selection--no names in call (SDDS_MatchArrays)");
    return -1;
  }
 
  if (SDDS_dataset->layout.n_arrays != flags) {
    flags = SDDS_dataset->layout.n_arrays;
    if (flag)
      free(flag);
    flag = NULL;
    if (flags) {
      if (!(flag = (int32_t *)calloc(flags, sizeof(*flag)))) {
        SDDS_SetError("Memory allocation failure (SDDS_MatchArrays)");
        return -1;
      }
    }
  }
  if (flags && (matchMode != SDDS_MATCH_STRING) && (matchMode != SDDS_MATCH_EXCLUDE_STRING))
    memset(flag, 0, sizeof(*flag) * flags);
 
  if ((matchMode != SDDS_MATCH_STRING) && (matchMode != SDDS_MATCH_EXCLUDE_STRING)) {
    for (i = 0; i < n_names; i++) {
      if ((index = SDDS_GetArrayIndex(SDDS_dataset, name[i])) >= 0)
        flag[index] = 1;
    }
  } else {
    for (i = 0; i < SDDS_dataset->layout.n_arrays; i++) {
      if (SDDS_Logic(flag[i], wild_match(SDDS_dataset->layout.array_definition[i].name, match_string), logic)) {
        if (exclude_string != NULL) {
          if (SDDS_Logic(flag[i], wild_match(SDDS_dataset->layout.array_definition[i].name, exclude_string), logic))
            flag[i] = 0;
          else
            flag[i] = 1;
        } else {
          flag[i] = 1;
        }
      } else {
#if defined(DEBUG)
        fprintf(stderr, "no logic match of %s to %s\n", SDDS_dataset->layout.array_definition[i].name, match_string);
#endif
        flag[i] = 0;
      }
    }
  }
  if (match_string)
    free(match_string);
  if (exclude_string)
    free(exclude_string);
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->layout.n_arrays; i++)
    fprintf(stderr, "flag[%" PRId32 "] = %" PRId32 " : %s\n", i, flag[i], SDDS_dataset->layout.array_definition[i].name);
#endif
 
  if (local_memory == 2) {
    for (i = 0; i < n_names; i++)
      free(name[i]);
  }
  if (local_memory >= 1)
    free(name);
 
  switch (typeMode) {
  case FIND_SPECIFIED_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_arrays; i++)
      if (SDDS_dataset->layout.array_definition[i].type != requiredType)
        flag[i] = 0;
    break;
  case FIND_NUMERIC_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_arrays; i++)
      if (!SDDS_NUMERIC_TYPE(SDDS_dataset->layout.array_definition[i].type))
        flag[i] = 0;
    break;
  case FIND_FLOATING_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_arrays; i++)
      if (!SDDS_FLOATING_TYPE(SDDS_dataset->layout.array_definition[i].type))
        flag[i] = 0;
    break;
  case FIND_INTEGER_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_arrays; i++)
      if (!SDDS_INTEGER_TYPE(SDDS_dataset->layout.array_definition[i].type))
        flag[i] = 0;
    break;
  default:
    break;
  }
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->layout.n_arrays; i++)
    if (flag[i])
      fprintf(stderr, "array %s matched\n", SDDS_dataset->layout.array_definition[i].name);
#endif
 
  for (i = matches = 0; i < SDDS_dataset->layout.n_arrays; i++) {
    if (flag[i])
      matches++;
  }
  if (!matches || !nameReturn)
    return matches;
  if (!((*nameReturn) = (char **)SDDS_Malloc(matches * sizeof(**nameReturn)))) {
    SDDS_SetError("Memory allocation failure (SDDS_MatchArrays)");
    return -1;
  }
  for (i = j = 0; i < SDDS_dataset->layout.n_arrays; i++) {
    if (flag[i]) {
      if (!SDDS_CopyString((*nameReturn) + j, SDDS_dataset->layout.array_definition[i].name)) {
        SDDS_SetError("String copy failure (SDDS_MatchArrays)");
        return -1;
      }
      j++;
    }
  }
 
  return matches;
}

SDDS_MatchColumns()

epicsShareFuncSDDS int32_t SDDS_MatchColumns ( SDDS_DATASET * SDDS_dataset, char *** nameReturn, int32_t matchMode, int32_t typeMode, ... )

extern

Matches and retrieves column names from an SDDS dataset based on specified criteria.

This function selects columns from the provided SDDS dataset according to the specified matching mode and type mode. It supports various calling conventions depending on the matching criteria.

The function supports the following matching modes:

• SDDS_NAME_ARRAY:
  • Parameters: int32_t n_entries, char **name
  • Description: Matches columns whose names are present in the provided array.
• SDDS_NAMES_STRING:
  • Parameters: char *names
  • Description: Matches columns whose names are specified in a single comma-separated string.
• SDDS_NAME_STRINGS:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Matches columns whose names are specified as individual string arguments, terminated by a NULL pointer.
• SDDS_MATCH_STRING:
  • Parameters: char *name, int32_t logic_mode
  • Description: Matches columns based on a wildcard pattern provided in name, using the specified logical mode.
• SDDS_MATCH_EXCLUDE_STRING:
  • Parameters: char *name, char *exclude, int32_t logic_mode
  • Description: Matches columns based on a wildcard pattern provided in name, excluding those that match the exclude pattern, using the specified logical mode.

Additionally, the typeMode parameter allows filtering based on column types, such as numeric, floating, or integer types.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure containing the dataset.
[out]	nameReturn	Pointer to a char** that will be allocated and populated with the names of the matched columns. The caller is responsible for freeing the allocated memory.
[in]	matchMode	Specifies the matching mode (e.g., SDDS_NAME_ARRAY, SDDS_NAMES_STRING, etc.).
[in]	typeMode	Specifies the type matching mode (e.g., FIND_SPECIFIED_TYPE, FIND_NUMERIC_TYPE, FIND_FLOATING_TYPE, FIND_INTEGER_TYPE).
[in]	...	Variable arguments depending on matchMode: SDDS_NAME_ARRAY: int32_t n_entries, char **name SDDS_NAMES_STRING: char *names SDDS_NAME_STRINGS: char *name1, char *name2, ..., NULL SDDS_MATCH_STRING: char *name, int32_t logic_mode SDDS_MATCH_EXCLUDE_STRING: char *name, char *exclude, int32_t logic_mode

Returns

• Returns the number of matched columns on success.
• Returns -1 if an error occurs (e.g., invalid parameters, memory allocation failure).

Note

• The function internally manages memory for the matching process and allocates memory for nameReturn, which must be freed by the caller using appropriate memory deallocation functions.
• The dataset must be properly initialized and contain a valid layout before calling this function.

Warning

• Ensure that the variable arguments match the expected parameters for the specified matchMode.
• The caller is responsible for freeing the memory allocated for nameReturn to avoid memory leaks.

See also

SDDS_MatchParameters, SDDS_SetError

Definition at line 3559 of file SDDS_utils.c.

{
  static MDB_THREAD_LOCAL int32_t flags = 0;
  static MDB_THREAD_LOCAL int32_t *flag = NULL;
  char **name, *string, *match_string, *ptr, *exclude_string;
  va_list argptr;
  int32_t retval, requiredType;
  int32_t i, j, n_names, index, matches;
  int32_t local_memory; /* (0,1,2) --> (none, pointer array, pointer array + strings) locally allocated */
  char buffer[SDDS_MAXLINE];
  int32_t logic;
 
  name = NULL;
  match_string = exclude_string = NULL;
  n_names = requiredType = local_memory = logic = 0;
 
  matches = -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_MatchColumns"))
    return -1;
  if (nameReturn)
    *nameReturn = NULL;
 
  retval = 1;
  va_start(argptr, typeMode);
  if (typeMode == FIND_SPECIFIED_TYPE)
    requiredType = va_arg(argptr, int32_t);
  switch (matchMode) {
  case SDDS_NAME_ARRAY:
    local_memory = 0;
    n_names = va_arg(argptr, int32_t);
    name = va_arg(argptr, char **);
    break;
  case SDDS_NAMES_STRING:
    local_memory = 2;
    n_names = 0;
    name = NULL;
    ptr = va_arg(argptr, char *);
    SDDS_CopyString(&string, ptr);
    while ((ptr = strchr(string, ',')))
      *ptr = ' ';
    while (SDDS_GetToken(string, buffer, SDDS_MAXLINE) > 0) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1))) || !SDDS_CopyString(name + n_names, buffer)) {
        SDDS_SetError("Unable to process column selection--memory allocation failure (SDDS_MatchColumns)");
        retval = 0;
        break;
      }
      n_names++;
    }
    free(string);
    break;
  case SDDS_NAME_STRINGS:
    local_memory = 1;
    n_names = 0;
    name = NULL;
    while ((string = va_arg(argptr, char *))) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1)))) {
        SDDS_SetError("Unable to process column selection--memory allocation failure (SDDS_MatchColumns)");
        retval = 0;
        break;
      }
      name[n_names++] = string;
    }
    break;
  case SDDS_MATCH_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process column selection--invalid matching string (SDDS_MatchColumns)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  case SDDS_MATCH_EXCLUDE_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process column selection--invalid matching string (SDDS_MatchColumns)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process column exclusion--invalid matching string (SDDS_MatchColumns)");
      retval = 0;
      break;
    }
    exclude_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  default:
    SDDS_SetError("Unable to process column selection--unknown match mode (SDDS_MatchColumns)");
    retval = 0;
    break;
  }
  va_end(argptr);
  if (retval == 0)
    return -1;
 
  if (n_names == 0) {
    SDDS_SetError("Unable to process column selection--no names in call (SDDS_MatchColumns)");
    return -1;
  }
 
  if (SDDS_dataset->layout.n_columns != flags) {
    flags = SDDS_dataset->layout.n_columns;
    if (flag)
      free(flag);
    flag = NULL;
    if (flags) {
      if (!(flag = (int32_t *)calloc(flags, sizeof(*flag)))) {
        SDDS_SetError("Memory allocation failure (SDDS_MatchColumns)");
        return -1;
      }
    }
  }
  if (flags && (matchMode != SDDS_MATCH_STRING) && (matchMode != SDDS_MATCH_EXCLUDE_STRING))
    memset(flag, 0, sizeof(*flag) * flags);
 
  if ((matchMode != SDDS_MATCH_STRING) && (matchMode != SDDS_MATCH_EXCLUDE_STRING)) {
    for (i = 0; i < n_names; i++) {
      if ((index = SDDS_GetColumnIndex(SDDS_dataset, name[i])) >= 0)
        flag[index] = 1;
    }
  } else {
    for (i = 0; i < SDDS_dataset->layout.n_columns; i++) {
      if (SDDS_Logic(flag[i], wild_match(SDDS_dataset->layout.column_definition[i].name, match_string), logic)) {
        if (exclude_string != NULL) {
          if (SDDS_Logic(flag[i], wild_match(SDDS_dataset->layout.column_definition[i].name, exclude_string), logic))
            flag[i] = 0;
          else
            flag[i] = 1;
        } else {
          flag[i] = 1;
        }
      } else {
#if defined(DEBUG)
        fprintf(stderr, "no logic match of %s to %s\n", SDDS_dataset->layout.column_definition[i].name, match_string);
#endif
        flag[i] = 0;
      }
    }
  }
  if (match_string)
    free(match_string);
  if (exclude_string)
    free(exclude_string);
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
    fprintf(stderr, "flag[%" PRId32 "] = %" PRId32 " : %s\n", i, flag[i], SDDS_dataset->layout.column_definition[i].name);
#endif
 
  if (local_memory == 2) {
    for (i = 0; i < n_names; i++)
      free(name[i]);
  }
  if (local_memory >= 1)
    free(name);
 
  switch (typeMode) {
  case FIND_SPECIFIED_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
      if (SDDS_dataset->layout.column_definition[i].type != requiredType)
        flag[i] = 0;
    break;
  case FIND_NUMERIC_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
      if (!SDDS_NUMERIC_TYPE(SDDS_dataset->layout.column_definition[i].type))
        flag[i] = 0;
    break;
  case FIND_FLOATING_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
      if (!SDDS_FLOATING_TYPE(SDDS_dataset->layout.column_definition[i].type))
        flag[i] = 0;
    break;
  case FIND_INTEGER_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
      if (!SDDS_INTEGER_TYPE(SDDS_dataset->layout.column_definition[i].type))
        flag[i] = 0;
    break;
  default:
    break;
  }
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
    if (flag[i])
      fprintf(stderr, "column %s matched\n", SDDS_dataset->layout.column_definition[i].name);
#endif
 
  for (i = matches = 0; i < SDDS_dataset->layout.n_columns; i++) {
    if (flag[i])
      matches++;
  }
  if (!matches || !nameReturn)
    return matches;
  if (!((*nameReturn) = (char **)SDDS_Malloc(matches * sizeof(**nameReturn)))) {
    SDDS_SetError("Memory allocation failure (SDDS_MatchColumns)");
    return -1;
  }
  for (i = j = 0; i < SDDS_dataset->layout.n_columns; i++) {
    if (flag[i]) {
      if (!SDDS_CopyString((*nameReturn) + j, SDDS_dataset->layout.column_definition[i].name)) {
        SDDS_SetError("String copy failure (SDDS_MatchColumns)");
        return -1;
      }
      j++;
    }
  }
  return matches;
}

SDDS_MatchParameters()

epicsShareFuncSDDS int32_t SDDS_MatchParameters ( SDDS_DATASET * SDDS_dataset, char *** nameReturn, int32_t matchMode, int32_t typeMode, ... )

extern

Matches and retrieves parameter names from an SDDS dataset based on specified criteria.

This function selects parameters from the provided SDDS dataset according to the specified matching mode and type mode. It supports various calling conventions depending on the matching criteria.

The function supports the following matching modes:

• SDDS_NAME_ARRAY:
  • Parameters: int32_t n_entries, char **name
  • Description: Matches parameters whose names are present in the provided array.
• SDDS_NAMES_STRING:
  • Parameters: char *names
  • Description: Matches parameters whose names are specified in a single comma-separated string.
• SDDS_NAME_STRINGS:
  • Parameters: char *name1, char *name2, ..., NULL
  • Description: Matches parameters whose names are specified as individual string arguments, terminated by a NULL pointer.
• SDDS_MATCH_STRING:
  • Parameters: char *name, int32_t logic_mode
  • Description: Matches parameters based on a wildcard pattern provided in name, using the specified logical mode.
• SDDS_MATCH_EXCLUDE_STRING:
  • Parameters: char *name, char *exclude, int32_t logic_mode
  • Description: Matches parameters based on a wildcard pattern provided in name, excluding those that match the exclude pattern, using the specified logical mode.

Additionally, the typeMode parameter allows filtering based on parameter types, such as numeric, floating, or integer types.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure containing the dataset.
[out]	nameReturn	Pointer to a char** that will be allocated and populated with the names of the matched parameters. The caller is responsible for freeing the allocated memory.
[in]	matchMode	Specifies the matching mode (e.g., SDDS_NAME_ARRAY, SDDS_NAMES_STRING, etc.).
[in]	typeMode	Specifies the type matching mode (e.g., FIND_SPECIFIED_TYPE, FIND_NUMERIC_TYPE, FIND_FLOATING_TYPE, FIND_INTEGER_TYPE).
[in]	...	Variable arguments depending on matchMode: SDDS_NAME_ARRAY: int32_t n_entries, char **name SDDS_NAMES_STRING: char *names SDDS_NAME_STRINGS: char *name1, char *name2, ..., NULL SDDS_MATCH_STRING: char *name, int32_t logic_mode SDDS_MATCH_EXCLUDE_STRING: char *name, char *exclude, int32_t logic_mode

Returns

• Returns the number of matched parameters on success.
• Returns -1 if an error occurs (e.g., invalid parameters, memory allocation failure).

Note

• The function internally manages memory for the matching process and allocates memory for nameReturn, which must be freed by the caller using appropriate memory deallocation functions.
• The dataset must be properly initialized and contain a valid layout before calling this function.

Warning

• Ensure that the variable arguments match the expected parameters for the specified matchMode.
• The caller is responsible for freeing the memory allocated for nameReturn to avoid memory leaks.

See also

SDDS_MatchColumns, SDDS_SetError

Definition at line 3840 of file SDDS_utils.c.

{
  static MDB_THREAD_LOCAL int32_t flags = 0, *flag = NULL;
  char **name, *string, *match_string, *ptr, *exclude_string;
  va_list argptr;
  int32_t i, j, index, n_names, retval, requiredType, matches;
  /*  int32_t type; */
  int32_t local_memory; /* (0,1,2) --> (none, pointer array, pointer array + strings) locally allocated */
  char buffer[SDDS_MAXLINE];
  int32_t logic;
 
  name = NULL;
  match_string = exclude_string = NULL;
  n_names = requiredType = local_memory = logic = 0;
 
  matches = -1;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_MatchParameters"))
    return -1;
  if (nameReturn)
    *nameReturn = NULL;
 
  retval = 1;
  va_start(argptr, typeMode);
  if (typeMode == FIND_SPECIFIED_TYPE)
    requiredType = va_arg(argptr, int32_t);
  switch (matchMode) {
  case SDDS_NAME_ARRAY:
    local_memory = 0;
    n_names = va_arg(argptr, int32_t);
    name = va_arg(argptr, char **);
    break;
  case SDDS_NAMES_STRING:
    local_memory = 2;
    n_names = 0;
    name = NULL;
    ptr = va_arg(argptr, char *);
    SDDS_CopyString(&string, ptr);
    while ((ptr = strchr(string, ',')))
      *ptr = ' ';
    while (SDDS_GetToken(string, buffer, SDDS_MAXLINE) > 0) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1))) || !SDDS_CopyString(name + n_names, buffer)) {
        SDDS_SetError("Unable to process parameter selection--memory allocation failure (SDDS_MatchParameters)");
        retval = 0;
        break;
      }
      n_names++;
    }
    free(string);
    break;
  case SDDS_NAME_STRINGS:
    local_memory = 1;
    n_names = 0;
    name = NULL;
    while ((string = va_arg(argptr, char *))) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1)))) {
        SDDS_SetError("Unable to process parameter selection--memory allocation failure (SDDS_MatchParameters)");
        retval = 0;
        break;
      }
      name[n_names++] = string;
    }
    break;
  case SDDS_MATCH_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process parameter selection--invalid matching string (SDDS_MatchParameters)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  case SDDS_MATCH_EXCLUDE_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process parameter selection--invalid matching string (SDDS_MatchParameters)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process parameter exclusion--invalid matching string (SDDS_MatchParameters)");
      retval = 0;
      break;
    }
    exclude_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  default:
    SDDS_SetError("Unable to process parameter selection--unknown match mode (SDDS_MatchParameters)");
    retval = 0;
    break;
  }
  va_end(argptr);
  if (retval == 0)
    return -1;
 
  if (n_names == 0) {
    SDDS_SetError("Unable to process parameter selection--no names in call (SDDS_MatchParameters)");
    return -1;
  }
 
  if (SDDS_dataset->layout.n_parameters != flags) {
    flags = SDDS_dataset->layout.n_parameters;
    if (flag)
      free(flag);
    flag = NULL;
    if (flags) {
      if (!(flag = (int32_t *)calloc(flags, sizeof(*flag)))) {
        SDDS_SetError("Memory allocation failure (SDDS_MatchParameters)");
        return -1;
      }
    }
  }
  if (flags && (matchMode != SDDS_MATCH_STRING) && (matchMode != SDDS_MATCH_EXCLUDE_STRING))
    memset(flag, 0, sizeof(*flag) * flags);
 
  if ((matchMode != SDDS_MATCH_STRING) && (matchMode != SDDS_MATCH_EXCLUDE_STRING)) {
    for (i = 0; i < n_names; i++) {
      if ((index = SDDS_GetParameterIndex(SDDS_dataset, name[i])) >= 0)
        flag[index] = 1;
    }
  } else {
    for (i = 0; i < SDDS_dataset->layout.n_parameters; i++) {
      if (SDDS_Logic(flag[i], wild_match(SDDS_dataset->layout.parameter_definition[i].name, match_string), logic)) {
        if (exclude_string != NULL) {
          if (SDDS_Logic(flag[i], wild_match(SDDS_dataset->layout.parameter_definition[i].name, exclude_string), logic))
            flag[i] = 0;
          else
            flag[i] = 1;
        } else {
          flag[i] = 1;
        }
      } else {
#if defined(DEBUG)
        fprintf(stderr, "no logic match of %s to %s\n", SDDS_dataset->layout.parameter_definition[i].name, match_string);
#endif
        flag[i] = 0;
      }
    }
  }
  if (match_string)
    free(match_string);
  if (exclude_string)
    free(exclude_string);
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->layout.n_parameters; i++)
    fprintf(stderr, "flag[%" PRId32 "] = %" PRId32 " : %s\n", i, flag[i], SDDS_dataset->layout.parameter_definition[i].name);
#endif
 
  if (local_memory == 2) {
    for (i = 0; i < n_names; i++)
      free(name[i]);
  }
  if (local_memory >= 1)
    free(name);
 
  switch (typeMode) {
  case FIND_SPECIFIED_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_parameters; i++)
      if (SDDS_dataset->layout.parameter_definition[i].type != requiredType)
        flag[i] = 0;
    break;
  case FIND_NUMERIC_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_parameters; i++)
      if (!SDDS_NUMERIC_TYPE(SDDS_dataset->layout.parameter_definition[i].type))
        flag[i] = 0;
    break;
  case FIND_FLOATING_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_parameters; i++)
      if (!SDDS_FLOATING_TYPE(SDDS_dataset->layout.parameter_definition[i].type))
        flag[i] = 0;
    break;
  case FIND_INTEGER_TYPE:
    for (i = 0; i < SDDS_dataset->layout.n_parameters; i++)
      if (!SDDS_INTEGER_TYPE(SDDS_dataset->layout.parameter_definition[i].type))
        flag[i] = 0;
    break;
  default:
    break;
  }
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->layout.n_parameters; i++)
    if (flag[i])
      fprintf(stderr, "parameter %s matched\n", SDDS_dataset->layout.parameter_definition[i].name);
#endif
 
  for (i = matches = 0; i < SDDS_dataset->layout.n_parameters; i++) {
    if (flag[i])
      matches++;
  }
  if (!matches || !nameReturn)
    return matches;
  if (!((*nameReturn) = (char **)SDDS_Malloc(matches * sizeof(**nameReturn)))) {
    SDDS_SetError("Memory allocation failure (SDDS_MatchParameters)");
    return -1;
  }
  for (i = j = 0; i < SDDS_dataset->layout.n_parameters; i++) {
    if (flag[i]) {
      if (!SDDS_CopyString((*nameReturn) + j, SDDS_dataset->layout.parameter_definition[i].name)) {
        SDDS_SetError("String copy failure (SDDS_MatchParameters)");
        return -1;
      }
      j++;
    }
  }
 
  return matches;
}

SDDS_MatchRowsOfInterest()

epicsShareFuncSDDS int64_t SDDS_MatchRowsOfInterest ( SDDS_DATASET * SDDS_dataset, char * selection_column, char * label_to_match, int32_t logic )

extern

Matches and marks rows of interest in an SDDS dataset based on label matching.

This function marks rows in the provided SDDS dataset as "of interest" by matching labels in a specified column against a target label. It supports both direct and indirect matching, as well as case-sensitive and case-insensitive comparisons, based on the provided logic flags.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
selection_column	A null-terminated string specifying the name of the column used for label matching. This column must be of string or character type.
label_to_match	A null-terminated string specifying the label to match against the entries in the selection column. If logic includes SDDS_INDIRECT_MATCH, this parameter is treated as the name of another column used for indirect matching.
logic	An integer representing logical operation flags. Supported flags include: SDDS_NOCASE_COMPARE: Perform case-insensitive comparison. SDDS_INDIRECT_MATCH: Use indirect matching via another column.

Returns

On success, returns the number of rows marked as "of interest". On failure, returns -1 and sets an appropriate error message.

Return values

-1	Indicates that an error occurred (e.g., invalid dataset, unrecognized selection column, type mismatch, unrecognized indirect column).
Non-negative	Integer representing the count of rows marked as "of interest".

Note

• The selection column must exist and be of string or character type.
• If using indirect matching (SDDS_INDIRECT_MATCH), the indirect column must exist and be of the same type as the selection column.

See also

SDDS_SetRowsOfInterest, SDDS_FilterRowsOfInterest, SDDS_DeleteUnsetRows

Definition at line 3507 of file SDDS_extract.c.

                                                                                                                          {
  int32_t match, type, index, indirect_index;
  int64_t i, count;
  char *match_string;
#ifndef tolower
#  if !defined(_MINGW)
  int tolower(int c);
#  endif
#endif
 
  index = type = indirect_index = 0;
 
  match_string = NULL;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_MatchRowsOfInterest"))
    return (-1);
  if (selection_column) {
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, selection_column)) < 0) {
      SDDS_SetError("Unable to select rows--column name is unrecognized (SDDS_MatchRowsOfInterest)");
      return (-1);
    }
    if ((type = SDDS_GetColumnType(SDDS_dataset, index)) != SDDS_STRING && type != SDDS_CHARACTER) {
      SDDS_SetError("Unable to select rows--selection column is not a string (SDDS_MatchRowsOfInterest)");
      return (-1);
    }
    if (!label_to_match) {
      SDDS_SetError("Unable to select rows--selection label is NULL (SDDS_MatchRowsOfInterest)");
      return (-1);
    }
    if (!(logic & SDDS_INDIRECT_MATCH))
      match_string = expand_ranges(label_to_match);
    else {
      if ((indirect_index = SDDS_GetColumnIndex(SDDS_dataset, label_to_match)) < 0) {
        SDDS_SetError("Unable to select rows--indirect column name is unrecognized (SDDS_MatchRowsOfInterest)");
        return (-1);
      }
      if (SDDS_GetColumnType(SDDS_dataset, indirect_index) != type) {
        SDDS_SetError("Unable to select rows--indirect column is not same type as main column (SDDS_MatchRowsOfInterest)");
        return (-1);
      }
    }
  }
  if (type == SDDS_STRING) {
    int (*stringCompare)(const char *s, const char *t);
    int (*wildMatch)(char *s, char *t);
    if (logic & SDDS_NOCASE_COMPARE) {
      stringCompare = strcmp_ci;
      wildMatch = wild_match_ci;
    } else {
      stringCompare = strcmp;
      wildMatch = wild_match;
    }
    for (i = count = 0; i < SDDS_dataset->n_rows; i++) {
      if (selection_column)
        match = SDDS_Logic(SDDS_dataset->row_flag[i], (logic & SDDS_INDIRECT_MATCH ? (*stringCompare)(*((char **)SDDS_dataset->data[index] + i), *((char **)SDDS_dataset->data[indirect_index] + i)) == 0 : (*wildMatch)(*((char **)SDDS_dataset->data[index] + i), match_string)), logic);
      else
        match = SDDS_Logic(SDDS_dataset->row_flag[i], 0, logic & ~(SDDS_AND | SDDS_OR));
      if ((SDDS_dataset->row_flag[i] = match))
        count++;
    }
  } else {
    char c1, c2;
    c2 = 0;
    if (!(logic & SDDS_INDIRECT_MATCH))
      c2 = *match_string;
    if (logic & SDDS_NOCASE_COMPARE) {
      c2 = tolower(c2);
      for (i = count = 0; i < SDDS_dataset->n_rows; i++) {
        c1 = tolower(*((char *)SDDS_dataset->data[index] + i));
        if (selection_column)
          match = SDDS_Logic(SDDS_dataset->row_flag[i], logic & SDDS_INDIRECT_MATCH ? c1 == tolower(*((char *)SDDS_dataset->data[indirect_index] + i)) : c1 == c2, logic);
        else
          match = SDDS_Logic(SDDS_dataset->row_flag[i], 0, logic & ~(SDDS_AND | SDDS_OR));
        if ((SDDS_dataset->row_flag[i] = match))
          count++;
      }
    } else {
      for (i = count = 0; i < SDDS_dataset->n_rows; i++) {
        c1 = *((char *)SDDS_dataset->data[index] + i);
        if (selection_column)
          match = SDDS_Logic(SDDS_dataset->row_flag[i], logic & SDDS_INDIRECT_MATCH ? c1 == *((char *)SDDS_dataset->data[indirect_index] + i) : c1 == c2, logic);
        else
          match = SDDS_Logic(SDDS_dataset->row_flag[i], 0, logic & ~(SDDS_AND | SDDS_OR));
        if ((SDDS_dataset->row_flag[i] = match))
          count++;
      }
    }
  }
  if (match_string)
    free(match_string);
  return (count);
}

SDDS_NumberOfErrors()

epicsShareFuncSDDS int32_t SDDS_NumberOfErrors ( void )

extern

Retrieves the number of errors recorded by SDDS library routines.

This function returns the total number of errors that have been recorded by the SDDS library since the last invocation of SDDS_PrintErrors.

Returns

The number of recorded errors.

See also

SDDS_PrintErrors

Definition at line 340 of file SDDS_utils.c.

                              {
  return (n_errors);
}

SDDS_PadToLength()

epicsShareFuncSDDS int32_t SDDS_PadToLength ( char * string, int32_t length )

extern

Pads a string with spaces to reach a specified length.

This function appends space characters to the end of the input string string until it reaches the desired length. If the original string is longer than the specified length, the function returns an error without modifying the string.

Parameters

[in,out]	string	Pointer to the null-terminated string to be padded.
[in]	length	The target length for the string after padding.

Returns

Returns 1 on successful padding. Returns 0 if the input string is NULL or if the original string length exceeds the specified length.

Note

The function ensures that the padded string is null-terminated. The caller must ensure that the buffer string has sufficient space to accommodate the additional padding.

See also

SDDS_RemovePadding

Definition at line 1945 of file SDDS_utils.c.

                                                       {
  int32_t i;
  if (!string || (i = strlen(string)) > length)
    return (0);
  while (i < length)
    string[i++] = ' ';
  string[i] = 0;
  return (1);
}

SDDS_Parallel_InitializeOutput()

epicsShareFuncSDDS int32_t SDDS_Parallel_InitializeOutput ( SDDS_DATASET * SDDS_dataset, const char * description, const char * contents, const char * filename )

extern

Initializes the SDDS output dataset for parallel processing.

This function configures the SDDS dataset for parallel output operations. It sets the dataset's description, contents, and filename, ensuring that the output is in binary mode as parallel processing with compressed files is not supported. The function initializes necessary structures and prepares the dataset for efficient parallel data writing.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be initialized for parallel output.
[in]	description	A string containing the description of the dataset. Pass NULL if no description is desired.
[in]	contents	A string detailing the contents of the dataset. Pass NULL if no contents are desired.
[in]	filename	The name of the file to which the dataset will be written. If NULL, the dataset will be written to standard output.

Returns

• 1 on successful initialization.
• 0 if an error occurred during initialization. In this case, an error message is set internally.

Precondition

• The SDDS_dataset pointer must be valid and point to a properly allocated SDDS_DATASET structure.
• The dataset memory should have been zeroed prior to calling this function (handled externally).

Postcondition

• The dataset is configured for parallel binary output.
• The dataset's internal state reflects the initialization status.

Note

• Parallel output does not support compressed file formats.
• The output mode is set to binary regardless of the specified data mode.
• Environment variable SDDS_OUTPUT_ENDIANESS can be set to "big" or "little" to declare the byte order.

Warning

• Attempting to use parallel initialization with compressed files will result in an error.
• Ensure that no other processes are accessing the file simultaneously to prevent initialization failures.

Definition at line 755 of file SDDS_output.c.

                                                                                                                                        {
  /*  SDDS_DATASET *SDDS_dataset; */
  char s[SDDS_MAXLINE];
  char *outputEndianess = NULL;
 
  /* SDDS_dataset = &(MPI_dataset->sdds_dataset); */
  if (sizeof(gzFile) != sizeof(void *)) {
    SDDS_SetError("gzFile is not the same size as void *, possible corruption of the SDDS_LAYOUT structure");
    return (0);
  }
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_InitializeOutput"))
    return 0;
  /* if (!SDDS_ZeroMemory((void *)SDDS_dataset, sizeof(SDDS_DATASET))) {
     sprintf(s,
     "Unable to initialize output for file %s--can't zero SDDS_DATASET structure (SDDS_InitializeOutput)",
     filename);
     SDDS_SetError(s);
     return 0;
     } */
  /*the sdds dataset memory has been zeroed in the SDDS_MPI_Setup */
  SDDS_dataset->layout.popenUsed = SDDS_dataset->layout.gzipFile = SDDS_dataset->layout.lzmaFile = SDDS_dataset->layout.disconnected = 0;
  SDDS_dataset->layout.depth = SDDS_dataset->layout.data_command_seen = SDDS_dataset->layout.commentFlags = SDDS_dataset->deferSavingLayout = 0;
  SDDS_dataset->layout.fp = NULL;
 
  SDDS_dataset->page_number = SDDS_dataset->page_started = 0;
  SDDS_dataset->file_had_data = SDDS_dataset->layout.layout_written = 0;
  if (!filename)
    SDDS_dataset->layout.filename = NULL;
  else if (!SDDS_CopyString(&SDDS_dataset->layout.filename, filename)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeOutput)", filename);
    SDDS_SetError(s);
    return 0;
  }
  if ((outputEndianess = getenv("SDDS_OUTPUT_ENDIANESS"))) {
    if (strncmp(outputEndianess, "big", 3) == 0)
      SDDS_dataset->layout.byteOrderDeclared = SDDS_BIGENDIAN;
    else if (strncmp(outputEndianess, "little", 6) == 0)
      SDDS_dataset->layout.byteOrderDeclared = SDDS_LITTLEENDIAN;
  } else {
    SDDS_dataset->layout.byteOrderDeclared = SDDS_IsBigEndianMachine() ? SDDS_BIGENDIAN : SDDS_LITTLEENDIAN;
  }
  /* set big-endian for binary files, since it is the only type of MPI binary file.
     SDDS_dataset->layout.byteOrderDeclared = SDDS_BIGENDIAN; */
  SDDS_dataset->layout.version = SDDS_VERSION;
  /* it turned out that hard to write ascii file in parallel, fixed it as SDDS_BINARY */
  SDDS_dataset->layout.data_mode.mode = SDDS_BINARY;
  SDDS_dataset->layout.data_mode.lines_per_row = 0;
  SDDS_dataset->layout.data_mode.no_row_counts = 0;
  SDDS_dataset->layout.data_mode.fixed_row_count = 0;
  SDDS_dataset->layout.data_mode.fsync_data = 0;
  SDDS_dataset->layout.data_mode.column_memory_mode = DEFAULT_COLUMN_MEMORY_MODE;
  /*This is only temporary, soon the default will be column major order */
  SDDS_dataset->layout.data_mode.column_major = 0;
  if (description && !SDDS_CopyString(&SDDS_dataset->layout.description, description)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeOutput)", filename ? filename : "stdout");
    SDDS_SetError(s);
    return 0;
  }
  if (contents && !SDDS_CopyString(&SDDS_dataset->layout.contents, contents)) {
    sprintf(s, "Memory allocation failure initializing file %s (SDDS_InitializeOutput)", filename ? filename : "stdout");
    SDDS_SetError(s);
    return 0;
  }
  SDDS_dataset->layout.n_parameters = SDDS_dataset->layout.n_columns = SDDS_dataset->layout.n_arrays = SDDS_dataset->layout.n_associates = 0;
  SDDS_dataset->mode = SDDS_WRITEMODE; /*writing */
  SDDS_dataset->pagecount_offset = NULL;
  SDDS_dataset->parallel_io = 1;
  return (1);
}

SDDS_ParameterCount()

epicsShareFuncSDDS int32_t SDDS_ParameterCount ( SDDS_DATASET * page )

extern

Retrieves the number of parameters in the SDDS dataset.

This function returns the total count of parameters defined in the layout of the provided SDDS dataset.

Parameters

[in]

page

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• The number of parameters (int32_t) in the dataset.
• 0 if the provided dataset pointer is NULL.

Note

• Ensure that the dataset is properly initialized before calling this function.

See also

SDDS_GetParameterIndex, SDDS_CheckParameter

Definition at line 5121 of file SDDS_utils.c.

                                                {
  if (!page)
    return 0;
  return page->layout.n_parameters;
}

SDDS_ParseNamelist()

epicsShareFuncSDDS int32_t SDDS_ParseNamelist ( void * data, SDDS_FIELD_INFORMATION * fieldInfo, int32_t fieldInfos, char * s )

extern

Parse a namelist string and populate the corresponding data structure.

This function parses a namelist string containing tag-value pairs and assigns the values to the appropriate fields in the provided data structure based on the field information provided.

Parameters

data	Pointer to the data structure to populate.
fieldInfo	Array of SDDS_FIELD_INFORMATION structures describing the fields.
fieldInfos	Number of elements in the fieldInfo array.
s	Pointer to the namelist string.

Returns

Returns 1 on success, 0 on failure.

Definition at line 588 of file SDDS_process.c.

                                                                                                       {
  char buffer[1024], *ptr, *tag, *value;
  int32_t index, longValue;
 
  ptr = SDDS_PrepareToParseTagValuePairs(s);
  while (*ptr && !SDDS_StringIsBlank(ptr) && (ptr = SDDS_GetTagValuePair(ptr, &tag, &value))) {
    if (!tag)
      break; /* normal termination */
    if ((index = SDDS_FindFieldIndex(tag, fieldInfo, fieldInfos)) < 0) {
      sprintf(buffer, "Unrecognized namelist tag given: %s", tag);
      SDDS_SetError(buffer);
      return 0;
    } else {
      if (fieldInfo[index].enumPair) {
        if (fieldInfo[index].type != SDDS_LONG) {
          fprintf(stderr, "SDDS_ParseNamelist: namelist setup problem---get expert help!\n");
          exit(1);
        }
        /* map a string value into an integer */
        if ((longValue = SDDS_MatchEnum(value, fieldInfo[index].enumPair)) < 0) {
          sprintf(buffer, "Unrecognized value given for %s: %s", tag, value);
          SDDS_SetError(buffer);
          return 0;
        } else
          *((int32_t *)((char *)data + fieldInfo[index].offset)) = longValue;
      } else {
        switch (fieldInfo[index].type) {
        case SDDS_STRING:
          if (!(SDDS_CopyString((char **)((char *)data + fieldInfo[index].offset), value))) {
            SDDS_SetError("Problem setting string value for namelist");
            return 0;
          }
          break;
        case SDDS_CHARACTER:
          *((char *)data + fieldInfo[index].offset) = *value;
          break;
        case SDDS_SHORT:
          if (!sscanf(value, "%hd", (short *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning short value for namelist");
            return 0;
          }
          break;
        case SDDS_USHORT:
          if (!sscanf(value, "%hu", (unsigned short *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning unsigned short value for namelist");
            return 0;
          }
          break;
        case SDDS_LONG:
          if (!sscanf(value, "%" SCNd32, (int32_t *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning int32_t value for namelist");
            return 0;
          }
          break;
        case SDDS_ULONG:
          if (!sscanf(value, "%" SCNu32, (uint32_t *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning uint32_t value for namelist");
            return 0;
          }
          break;
        case SDDS_LONG64:
          if (!sscanf(value, "%" SCNd64, (int64_t *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning int64_t value for namelist");
            return 0;
          }
          break;
        case SDDS_ULONG64:
          if (!sscanf(value, "%" SCNu64, (uint64_t *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning uint64_t value for namelist");
            return 0;
          }
          break;
        case SDDS_LONGDOUBLE:
          if (!sscanf(value, "%Lf", (long double *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning long double value for namelist");
            return 0;
          }
          break;
        case SDDS_DOUBLE:
          if (!sscanf(value, "%lf", (double *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning double value for namelist");
            return 0;
          }
          break;
        case SDDS_FLOAT:
          if (!sscanf(value, "%f", (float *)((char *)data + fieldInfo[index].offset))) {
            SDDS_SetError("Problem scanning float value for namelist");
            return 0;
          }
          break;
        default:
          SDDS_SetError("Internal error: unknown field information type");
          return 0;
        }
      }
    }
  }
  if (!ptr) {
    SDDS_SetError("Problem parsing description namelist");
    return 0;
  }
  return 1;
}

SDDS_PrintCheckText()

epicsShareFuncSDDS int32_t SDDS_PrintCheckText ( FILE * fp, char * name, char * units, int32_t type, char * class_name, int32_t error_code )

extern

Prints detailed error messages related to SDDS entity checks.

This function outputs error messages to the specified file pointer based on the provided error code. It is primarily used by functions like SDDS_CheckColumn, SDDS_CheckParameter, and SDDS_CheckArray to report issues during validation checks.

Parameters

[in]	fp	File pointer where the error messages will be printed. Typically, this is stderr.
[in]	name	The name of the SDDS entity (e.g., column, parameter, array) being checked.
[in]	units	The expected units of the SDDS entity. May be NULL if units are not relevant.
[in]	type	The expected type code of the SDDS entity. This can be a specific type or a general category like SDDS_ANY_NUMERIC_TYPE.
[in]	class_name	A string representing the class of the SDDS entity (e.g., "column", "parameter", "array").
[in]	error_code	The specific error code indicating the type of error encountered. Valid values include: SDDS_CHECK_OKAY SDDS_CHECK_NONEXISTENT SDDS_CHECK_WRONGTYPE SDDS_CHECK_WRONGUNITS

Returns

Returns the same error_code that was passed as an argument.

Note

• This function assumes that registeredProgramName is a globally accessible string containing the name of the program for contextual error messages.
• Ensure that fp, name, and class_name are not NULL to prevent undefined behavior.

Warning

• Passing invalid error_code values that are not handled in the switch statement will result in a generic error message being printed to stderr.

See also

SDDS_CheckColumn, SDDS_CheckParameter, SDDS_CheckArray

Definition at line 4914 of file SDDS_utils.c.

                                                                                                                   {
  char *programName;
  const char *programNameText;
 
  if (!fp || !name || !class_name)
    return (error_code);
  programName = SDDS_GetRegisteredProgramNameCopy();
  programNameText = programName ? programName : "?";
  switch (error_code) {
  case SDDS_CHECK_OKAY:
    break;
  case SDDS_CHECK_NONEXISTENT:
    fprintf(fp, "Problem with %s %s: nonexistent (%s)\n", class_name, name, programNameText);
    break;
  case SDDS_CHECK_WRONGTYPE:
    if (SDDS_VALID_TYPE(type))
      fprintf(fp, "Problem with %s %s: wrong data type--expected %s (%s)\n", class_name, name, SDDS_type_name[type - 1], programNameText);
    else if (type == SDDS_ANY_NUMERIC_TYPE)
      fprintf(fp, "Problem with %s %s: wrong data type--expected numeric data (%s)\n", class_name, name, programNameText);
    else if (type == SDDS_ANY_FLOATING_TYPE)
      fprintf(fp, "Problem with %s %s: wrong data type--expected floating point data (%s)\n", class_name, name, programNameText);
    else if (type == SDDS_ANY_INTEGER_TYPE)
      fprintf(fp, "Problem with %s %s: wrong data type--expected integer data (%s)\n", class_name, name, programNameText);
    else if (type)
      fprintf(fp, "Problem with %s %s: invalid data type code seen---may be a programming error (%s)\n", class_name, name, programNameText);
    break;
  case SDDS_CHECK_WRONGUNITS:
    fprintf(fp, "Problem with %s %s: wrong units--expected %s (%s)\n", class_name, name, units ? units : "none", programNameText);
    break;
  default:
    fprintf(stderr, "Problem with call to SDDS_PrintCheckText--invalid error code (%s)\n", programNameText);
    free(programName);
    return (SDDS_CHECK_OKAY);
  }
  free(programName);
  return (error_code);
}

SDDS_PrintErrors()

epicsShareFuncSDDS void SDDS_PrintErrors ( FILE * fp, int32_t mode )

extern

Prints recorded error messages to a specified file stream.

This function outputs the errors that have been recorded by SDDS library routines to the given file stream. Depending on the mode parameter, it can print a single error, all recorded errors, and optionally terminate the program after printing.

Parameters

[in]	fp	Pointer to the FILE stream where errors will be printed. Typically stderr.
[in]	mode	Flags controlling the error printing behavior: 0: Print only the first recorded error. SDDS_VERBOSE_PrintErrors: Print all recorded errors. SDDS_EXIT_PrintErrors: After printing errors, terminate the program by calling exit(1).

Note

After printing, the error stack is cleared. If mode includes SDDS_EXIT_PrintErrors, the program will terminate.

See also

SDDS_SetError

SDDS_NumberOfErrors

SDDS_ClearErrors

Definition at line 474 of file SDDS_utils.c.

                                              {
  int32_t i, depth;
  char *programName;
 
  if (!n_errors)
    return;
  if (!fp) {
    SDDS_ClearErrors();
    return;
  }
  if (mode & SDDS_VERBOSE_PrintErrors)
    depth = n_errors;
  else
    depth = 1;
  programName = SDDS_GetRegisteredProgramNameCopy();
  if (programName)
    fprintf(fp, "Error for %s:\n", programName);
  else
    fputs("Error:\n", fp);
  free(programName);
  if (!error_description)
    fprintf(stderr, "warning: internal error: error_description pointer is unexpectedly NULL\n");
  else
    for (i = 0; i < depth; i++) {
      if (!error_description[i])
        fprintf(stderr, "warning: internal error: error_description[%" PRId32 "] is unexpectedly NULL\n", i);
      else
        fprintf(fp, "%s", error_description[i]);
    }
  fflush(fp);
  SDDS_ClearErrors();
  if (mode & SDDS_EXIT_PrintErrors)
    exit(1);
}

SDDS_PrintTypedValue()

epicsShareFuncSDDS int32_t SDDS_PrintTypedValue ( void * data, int64_t index, int32_t type, char * format, FILE * fp, uint32_t mode )

extern

Prints a data value of a specified type using an optional printf format string.

This function prints a single data value from a data array based on the specified type and index. It supports various data types defined by SDDS constants and allows customization of the output format.

Parameters

[in]	data	Pointer to the base address of the data array to be printed.
[in]	index	The index of the item within the data array to be printed.
[in]	type	The data type of the value to be printed, specified by one of the SDDS constants: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	format	(Optional) NULL-terminated string specifying a printf format. If NULL, a default format is used based on the data type.
[in]	fp	Pointer to the FILE stream where the data will be printed.
[in]	mode	Flags controlling the printing behavior. Valid values are: 0: Default behavior. SDDS_PRINT_NOQUOTES: When printing strings, do not enclose them in quotes.

Returns

Returns 1 on success. On failure, returns 0 and records an error message.

Note

This function assumes that the data pointer points to an array of the specified type, and index is within the bounds of this array.

See also

SDDS_SetError

Definition at line 67 of file SDDS_utils.c.

                                                                                                             {
  char buffer[SDDS_PRINT_BUFLEN], *s;
 
  if (!data) {
    SDDS_SetError("Unable to print value--data pointer is NULL (SDDS_PrintTypedValue)");
    return (0);
  }
  if (!fp) {
    SDDS_SetError("Unable to print value--file pointer is NULL (SDDS_PrintTypedValue)");
    return (0);
  }
  switch (type) {
  case SDDS_SHORT:
    fprintf(fp, format ? format : "%hd", *((short *)data + index));
    break;
  case SDDS_USHORT:
    fprintf(fp, format ? format : "%hu", *((unsigned short *)data + index));
    break;
  case SDDS_LONG:
    fprintf(fp, format ? format : "%" PRId32, *((int32_t *)data + index));
    break;
  case SDDS_ULONG:
    fprintf(fp, format ? format : "%" PRIu32, *((uint32_t *)data + index));
    break;
  case SDDS_LONG64:
    fprintf(fp, format ? format : "%" PRId64, *((int64_t *)data + index));
    break;
  case SDDS_ULONG64:
    fprintf(fp, format ? format : "%" PRIu64, *((uint64_t *)data + index));
    break;
  case SDDS_FLOAT:
    fprintf(fp, format ? format : "%15.8e", *((float *)data + index));
    break;
  case SDDS_DOUBLE:
    fprintf(fp, format ? format : "%21.15e", *((double *)data + index));
    break;
  case SDDS_LONGDOUBLE:
    if (LDBL_DIG == 18) {
      fprintf(fp, format ? format : "%21.18Le", *((long double *)data + index));
    } else {
      fprintf(fp, format ? format : "%21.15Le", *((long double *)data + index));
    }
    break;
  case SDDS_STRING:
    s = *((char **)data + index);
    if ((int32_t)strlen(s) > SDDS_PRINT_BUFLEN - 3) {
      SDDS_SetError("Buffer size overflow (SDDS_PrintTypedValue)");
      return 0;
    }
    SDDS_SprintTypedValue(data, index, type, format, buffer, mode);
    fputs(buffer, fp);
    break;
  case SDDS_CHARACTER:
    fprintf(fp, format ? format : "%c", *((char *)data + index));
    break;
  default:
    SDDS_SetError("Unable to print value--unknown data type (SDDS_PrintTypedValue)");
    return (0);
  }
  return (1);
}

SDDS_ProcessArrayString()

epicsShareFuncSDDS int32_t SDDS_ProcessArrayString ( SDDS_DATASET * SDDS_dataset, char * string )

extern

Process an array definition string.

This function parses a string containing array definition information and updates the SDDS dataset accordingly.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure.
string	Pointer to the array definition string.

Returns

Returns 1 on success, 0 on failure.

Definition at line 362 of file SDDS_process.c.

                                                                          {
  char *ptr1, *ptr2;
  char *s;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ProcessArrayString"))
    return (0);
  if (!string)
    return (0);
  if (!SDDS_CopyString(&s, string))
    return 0;
  if (!(ptr1 = strchr(s, '&')) || !(ptr2 = strchr(ptr1, ' '))) {
    free(s);
    return 0;
  }
  *ptr2 = 0;
  if (strcmp(ptr1, "&array") != 0) {
    free(s);
    return (0);
  }
  if (SDDS_ProcessArrayDefinition(SDDS_dataset, ptr2 + 1)) {
    free(s);
    if (!SDDS_SaveLayout(SDDS_dataset))
      return (0);
    return (1);
  }
  free(s);
  return (0);
}

SDDS_ProcessAssociateString()

epicsShareFuncSDDS int32_t SDDS_ProcessAssociateString ( SDDS_DATASET * SDDS_dataset, char * string )

extern

Process an associate definition string.

This function parses a string containing associate definition information and updates the SDDS dataset accordingly.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure.
string	Pointer to the associate definition string.

Returns

Returns 1 on success, 0 on failure.

Definition at line 400 of file SDDS_process.c.

                                                                              {
  char *ptr1, *ptr2;
  char *s;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ProcessAssociateString"))
    return (0);
  if (!string)
    return (0);
  if (!SDDS_CopyString(&s, string))
    return 0;
  if (!(ptr1 = strchr(s, '&')) || !(ptr2 = strchr(ptr1, ' '))) {
    free(s);
    return 0;
  }
  *ptr2 = 0;
  if (strcmp(ptr1, "&associate") != 0) {
    free(s);
    return (0);
  }
  *ptr2 = ' ';
  if (SDDS_ProcessAssociateDefinition(SDDS_dataset, ptr2 + 1)) {
    free(s);
    if (!SDDS_SaveLayout(SDDS_dataset))
      return (0);
    return (1);
  }
  free(s);
  return (0);
}

SDDS_ProcessColumnString()

epicsShareFuncSDDS int32_t SDDS_ProcessColumnString ( SDDS_DATASET * SDDS_dataset, char * string, int32_t mode )

extern

Process a column definition string.

This function parses a string containing column definition information and updates the SDDS dataset accordingly.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure.
string	Pointer to the column definition string.
mode	Mode indicating how the column is defined.

Returns

Returns 1 on success, 0 on failure.

Definition at line 283 of file SDDS_process.c.

                                                                                         {
  char *ptr1, *ptr2;
  char *s;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ProcessColumnString"))
    return (0);
  if (!string)
    return (0);
  if (!SDDS_CopyString(&s, string))
    return 0;
  if (!(ptr1 = strchr(s, '&')) || !(ptr2 = strchr(ptr1, ' '))) {
    free(s);
    return 0;
  }
  *ptr2 = 0;
  if (strcmp(ptr1, "&column") != 0) {
    free(s);
    return (0);
  }
  if (SDDS_ProcessColumnDefinition(SDDS_dataset, ptr2 + 1)) {
    free(s);
    SDDS_dataset->layout.column_definition[SDDS_dataset->layout.n_columns - 1].definition_mode = mode;
    if (!SDDS_SaveLayout(SDDS_dataset))
      return (0);
    return (1);
  }
  free(s);
  return (0);
}

SDDS_ProcessParameterString()

epicsShareFuncSDDS int32_t SDDS_ProcessParameterString ( SDDS_DATASET * SDDS_dataset, char * string, int32_t mode )

extern

Process a parameter definition string.

This function parses a string containing parameter definition information and updates the SDDS dataset accordingly.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure.
string	Pointer to the parameter definition string.
mode	Mode indicating how the parameter is defined.

Returns

Returns 1 on success, 0 on failure.

Definition at line 323 of file SDDS_process.c.

                                                                                            {
  char *ptr1, *ptr2;
  char *s;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ProcessParameterString"))
    return (0);
  if (!string)
    return (0);
  if (!SDDS_CopyString(&s, string))
    return 0;
  if (!(ptr1 = strchr(s, '&')) || !(ptr2 = strchr(ptr1, ' '))) {
    free(s);
    return 0;
  }
  *ptr2 = 0;
  if (strcmp(ptr1, "&parameter") != 0) {
    free(s);
    return (0);
  }
  if (SDDS_ProcessParameterDefinition(SDDS_dataset, ptr2 + 1)) {
    free(s);
    SDDS_dataset->layout.parameter_definition[SDDS_dataset->layout.n_parameters - 1].definition_mode = mode;
    if (!SDDS_SaveLayout(SDDS_dataset))
      return (0);
    return (1);
  }
  free(s);
  return (0);
}

SDDS_ReadAsciiPage()

epicsShareFuncSDDS int32_t SDDS_ReadAsciiPage ( SDDS_DATASET * SDDS_dataset, int64_t sparse_interval, int64_t sparse_offset, int32_t sparse_statistics )

extern

Reads the next SDDS ASCII page into memory with optional data sparsity and statistics.

This function reads the next page of data from an ASCII SDDS file into the provided dataset. It supports reading data with specified sparsity (interval and offset) and can compute statistics such as average, median, minimum, or maximum over the sparse data.

Parameters

SDDS_dataset	Pointer to the SDDS dataset where the data will be stored.
sparse_interval	Interval for sparsity; read every nth row if greater than 1.
sparse_offset	Offset for sparsity; number of initial rows to skip.
sparse_statistics	Statistic to compute over the sparse data: 0: None 1: Average 2: Median 3: Minimum 4: Maximum

Returns

Returns the page number on success, -1 if end-of-file is reached, or 0 on error.

Note

The function utilizes SDDS_ReadAsciiPageDetailed() to perform the actual reading.

Definition at line 1225 of file SDDS_ascii.c.

                                                                                                                                  {
  return SDDS_ReadAsciiPageDetailed(SDDS_dataset, sparse_interval, sparse_offset, 0, sparse_statistics);
}

SDDS_ReadLayout()

epicsShareFuncSDDS int32_t SDDS_ReadLayout ( SDDS_DATASET * SDDS_dataset, FILE * fp )

extern

Reads the header layout of an SDDS dataset from a file.

Parameters

SDDS_dataset	The SDDS dataset structure to store the layout information.
fp	The file pointer to the SDDS file.

Returns

Returns 1 on success, 0 on failure.

Definition at line 518 of file SDDS_input.c.

                                                              {
  char buffer[SDDS_MAXLINE];
  char *groupName, *ptr;
  FILE *fp1;
  int32_t retval, bigEndianMachine;
  uint32_t commentFlags;
 
  if (!fp) {
    SDDS_SetError("Unable to read layout--NULL file pointer (SDDS_ReadLayout)");
    return (0);
  }
  if (SDDS_dataset->layout.depth == 0) {
    if (SDDS_dataset->layout.disconnected) {
      SDDS_SetError("Can't read layout--file is disconnected (SDDS_ReadLayout)");
      return 0;
    }
    if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReadLayout")) {
      fclose(fp);
      return (0);
    }
    SDDS_dataset->layout.layout_written = 1; /* it is already in the file */
    if (!fgets(SDDS_dataset->layout.s, SDDS_MAXLINE, fp)) {
      fclose(fp);
      SDDS_SetError("Unable to read layout--no header lines found (SDDS_ReadLayout)");
      return (0);
    }
    if (strncmp(SDDS_dataset->layout.s, "SDDS", 4) != 0) {
      fclose(fp);
      SDDS_SetError("Unable to read layout--no header lines found (SDDS_ReadLayout)");
      return (0);
    }
    if (sscanf(SDDS_dataset->layout.s + 4, "%" SCNd32, &SDDS_dataset->layout.version) != 1) {
      fclose(fp);
      SDDS_SetError("Unable to read layout--no version number on first line (SDDS_ReadLayout)");
      return (0);
    }
    SDDS_ResetSpecialCommentsModes(SDDS_dataset);
    SDDS_dataset->layout.data_command_seen = 0;
  }
  while (SDDS_GetNamelist(SDDS_dataset, SDDS_dataset->layout.s, SDDS_MAXLINE, fp)) {
#if DEBUG
    strcpy(buffer, SDDS_dataset->layout.s);
#endif
    groupName = SDDS_dataset->layout.s + 1;
    if (!(ptr = strpbrk(SDDS_dataset->layout.s, " \t"))) {
      SDDS_SetError("Unable to read layout---no groupname in namelist (SDDS_ReadLayout)");
      return 0;
    }
    *ptr = 0;
    switch (match_string(groupName, SDDS_command, SDDS_NUM_COMMANDS, EXACT_MATCH)) {
    case SDDS_DESCRIPTION_COMMAND:
      if (!SDDS_ProcessDescription(SDDS_dataset, ptr + 1)) {
        fclose(fp);
        SDDS_SetError("Unable to process description (SDDS_ReadLayout)");
        return (0);
      }
      break;
    case SDDS_COLUMN_COMMAND:
      if (!SDDS_ProcessColumnDefinition(SDDS_dataset, ptr + 1)) {
        fclose(fp);
        SDDS_SetError("Unable to process column definition (SDDS_ReadLayout)");
        return (0);
      }
      break;
    case SDDS_PARAMETER_COMMAND:
      if (!SDDS_ProcessParameterDefinition(SDDS_dataset, ptr + 1)) {
        fclose(fp);
        SDDS_SetError("Unable to process parameter definition (SDDS_ReadLayout)");
        return (0);
      }
      break;
    case SDDS_ASSOCIATE_COMMAND:
#if RW_ASSOCIATES != 0
      if (!SDDS_ProcessAssociateDefinition(SDDS_dataset, ptr + 1)) {
        fclose(fp);
        SDDS_SetError("Unable to process associate definition (SDDS_ReadLayout)");
        return (0);
      }
#endif
      break;
    case SDDS_DATA_COMMAND:
      if (!SDDS_ProcessDataMode(SDDS_dataset, ptr + 1)) {
        fclose(fp);
        SDDS_SetError("Unable to process data mode (SDDS_ReadLayout)");
        return (0);
      }
      if (SDDS_dataset->layout.data_command_seen) {
        /* should never happen */
        fclose(fp);
        SDDS_SetError("Unable to read layout--multiple data commands (SDDS_ReadLayout)");
        return (0);
      }
      if (!SDDS_SaveLayout(SDDS_dataset)) {
        SDDS_SetError("Unable to read layout--couldn't save layout (SDDS_ReadLayout)");
        return (0);
      }
      SDDS_dataset->layout.data_command_seen = 1;
      commentFlags = SDDS_GetSpecialCommentsModes(SDDS_dataset);
      if ((commentFlags & SDDS_BIGENDIAN_SEEN) && (commentFlags & SDDS_LITTLEENDIAN_SEEN)) {
        SDDS_SetError("Unable to read data as it says it is both big and little endian (SDDS_ReadLayout)");
        return (0);
      }
      bigEndianMachine = SDDS_IsBigEndianMachine();
      SDDS_dataset->swapByteOrder = SDDS_dataset->layout.byteOrderDeclared = 0;
      SDDS_dataset->autoRecover = 0;
      if ((commentFlags & SDDS_BIGENDIAN_SEEN) || (SDDS_dataset->layout.data_mode.endian == SDDS_BIGENDIAN)) {
        SDDS_dataset->layout.byteOrderDeclared = SDDS_BIGENDIAN_SEEN;
        if (!bigEndianMachine)
          SDDS_dataset->swapByteOrder = 1;
      }
      if ((commentFlags & SDDS_LITTLEENDIAN_SEEN) || (SDDS_dataset->layout.data_mode.endian == SDDS_LITTLEENDIAN)) {
        SDDS_dataset->layout.byteOrderDeclared = SDDS_LITTLEENDIAN_SEEN;
        if (bigEndianMachine)
          SDDS_dataset->swapByteOrder = 1;
      }
      if ((commentFlags & SDDS_FIXED_ROWCOUNT_SEEN) || (SDDS_dataset->layout.data_mode.fixed_row_count))
        if (!SDDS_SetAutoReadRecovery(SDDS_dataset, SDDS_AUTOREADRECOVER))
          return (0);
      return (1);
    case SDDS_INCLUDE_COMMAND:
      if (!(fp1 = SDDS_ProcessIncludeCommand(SDDS_dataset, ptr + 1))) {
        fclose(fp);
        SDDS_SetError("Unable to process include command (SDDS_ReadLayout)");
        return (0);
      }
      SDDS_dataset->layout.depth += 1;
      retval = SDDS_ReadLayout(SDDS_dataset, fp1);
      SDDS_dataset->layout.depth -= 1;
      fclose(fp1);
      if (retval == 0) {
        return (0);
      }
      if (SDDS_dataset->layout.data_command_seen) {
        return (1);
      }
      break;
    case SDDS_ARRAY_COMMAND:
      if (!SDDS_ProcessArrayDefinition(SDDS_dataset, ptr + 1)) {
        fclose(fp);
        SDDS_SetError("Unable to process array definition (SDDS_ReadLayout)");
        return (0);
      }
      break;
    default:
      fclose(fp);
      sprintf(buffer, "Unknown layout entry %s given (SDDS_ReadLayout)", groupName);
      SDDS_SetError(buffer);
      return (0);
    }
  }
  /* on recursive calls, it's okay to hit EOF */
  if ((feof(fp) && SDDS_dataset->layout.depth != 0) || SDDS_dataset->layout.data_command_seen)
    return (1);
  return (0);
}

SDDS_ReadNewBinaryRows()

epicsShareFuncSDDS int32_t SDDS_ReadNewBinaryRows ( SDDS_DATASET * SDDS_dataset )

extern

Reads new binary rows from the SDDS dataset.

This function updates the SDDS dataset by reading any new rows that have been added to the underlying file since the last read operation. It verifies that the dataset is in a compatible binary format and ensures that byte order and compression settings are supported. If the number of rows in the file exceeds the currently allocated rows in memory, the function expands the dataset's internal storage to accommodate the new rows.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to read from.

Returns

int32_t Returns the number of new rows successfully read on success, or -1 if an error occurred.

Return values

>0	The number of new rows read and added to the dataset.
-1	An error occurred during the read operation, such as unsupported file format, I/O errors, or memory allocation failures.

Note

This function does not support MPI parallel I/O, ASCII files, column-major order binary files, non-native byte orders, or compressed files (gzip or lzma). Attempts to use these features will result in an error.

Definition at line 2962 of file SDDS_binary.c.

                                                           {
  int64_t row, offset, newRows = 0;
  int32_t rowsPresent32;
  int64_t rowsPresent;
 
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io) {
    SDDS_SetError("Error: MPI mode not supported yet in SDDS_ReadNewBinaryRows");
    return -1;
  }
#endif
  if (SDDS_dataset->original_layout.data_mode.mode == SDDS_ASCII) {
    SDDS_SetError("Error: ASCII files not supported in SDDS_ReadNewBinaryRows");
    return -1;
  }
  if (SDDS_dataset->layout.data_mode.column_major) {
    SDDS_SetError("Error: column-major order binary files not supported in SDDS_ReadNewBinaryRows");
    return -1;
  }
  if (SDDS_dataset->swapByteOrder) {
    SDDS_SetError("Error: Non-native endian not supported yet in SDDS_ReadNewBinaryRows");
    return -1;
  }
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    SDDS_SetError("Error: gzip compressed files not supported yet in SDDS_ReadNewBinaryRows");
    return -1;
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      SDDS_SetError("Error: lzma compressed files not supported yet in SDDS_ReadNewBinaryRows");
      return -1;
    }
#if defined(zLib)
  }
#endif
 
  // Read how many rows we have now
  offset = ftell(SDDS_dataset->layout.fp);
  fseek(SDDS_dataset->layout.fp, SDDS_dataset->rowcount_offset, 0);
  if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY) {
    if (fread(&rowsPresent32, sizeof(rowsPresent32), 1, SDDS_dataset->layout.fp) == 0) {
      SDDS_SetError("Error: row count not present or not correct length");
      return -1;
    }
    if (SDDS_dataset->swapByteOrder) {
      SDDS_SwapLong(&rowsPresent32);
    }
    if (rowsPresent32 == INT32_MIN) {
      if (fread(&rowsPresent, sizeof(rowsPresent), 1, SDDS_dataset->layout.fp) == 0) {
        SDDS_SetError("Error: row count not present or not correct length");
        return -1;
      }
      if (SDDS_dataset->swapByteOrder) {
        SDDS_SwapLong64(&rowsPresent);
      }
    } else {
      rowsPresent = rowsPresent32;
    }
  } else {
    char buffer[30];
    if (!fgets(buffer, 30, SDDS_dataset->layout.fp) || strlen(buffer) != 21 || sscanf(buffer, "%" SCNd64, &rowsPresent) != 1) {
      SDDS_SetError("Error: row count not present or not correct length");
      return -1;
    }
  }
  fseek(SDDS_dataset->layout.fp, offset, 0);
 
  // If the row count listed in the file is greather than the allocated rows, then lengthen the table in memory
  if (rowsPresent > SDDS_dataset->n_rows_allocated) {
    if (!SDDS_LengthenTable(SDDS_dataset, rowsPresent + 3)) {
      return -1;
    }
  }
 
  for (row = SDDS_dataset->n_rows; row < rowsPresent; row++) {
    if (!SDDS_ReadBinaryRow(SDDS_dataset, row, 0)) {
      if (SDDS_dataset->autoRecover) {
        row--;
        SDDS_dataset->autoRecovered = 1;
        SDDS_ClearErrors();
        break;
      }
      SDDS_SetError("Unable to read page--error reading data row");
      return -1;
    }
  }
  newRows = row + 1 - SDDS_dataset->n_rows;
  SDDS_dataset->n_rows = row + 1;
  return newRows;
}

SDDS_ReadNonNativeBinaryArrays()

int32_t SDDS_ReadNonNativeBinaryArrays

(

SDDS_DATASET *

SDDS_dataset

)

Reads non-native endian binary arrays from an SDDS dataset.

This function iterates through all array definitions in the specified SDDS dataset and reads their binary data from the underlying file. It handles various data types, including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. For string arrays, it reads each string individually, ensuring proper memory allocation and byte order conversion. The function supports different compression formats, including uncompressed, LZMA-compressed, and GZIP-compressed files. After reading, it swaps the endianness of the array data to match the system's native byte order.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to read from.

Returns

int32_t Returns 1 on successful reading and byte-swapping of all arrays, or 0 if an error occurred.

Return values

1	All non-native endian arrays were successfully read and byte-swapped.
0	An error occurred during the read or byte-swapping process, such as I/O failures, memory allocation issues, or corrupted array definitions.

Note

This function modifies the dataset's array data in place. It should be called after successfully opening and preparing the dataset for reading. Ensure that the dataset structure is properly initialized to prevent undefined behavior.

Definition at line 4708 of file SDDS_binary.c.

                                                                   {
  int32_t i, j;
  SDDS_LAYOUT *layout;
  /*  char *predefined_format; */
  /*  static char buffer[SDDS_MAXLINE]; */
#if defined(zLib)
  gzFile gzfp = NULL;
#endif
  FILE *fp = NULL;
  struct lzmafile *lzmafp = NULL;
  SDDS_ARRAY *array;
  SDDS_FILEBUFFER *fBuffer;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReadNonNativeBinaryArrays"))
    return (0);
  layout = &SDDS_dataset->layout;
  if (!layout->n_arrays)
    return (1);
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    gzfp = layout->gzfp;
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      lzmafp = layout->lzmafp;
    } else {
      fp = layout->fp;
    }
#if defined(zLib)
  }
#endif
  fBuffer = &SDDS_dataset->fBuffer;
  if (!SDDS_dataset->array) {
    SDDS_SetError("Unable to read array--pointer to structure storage area is NULL (SDDS_ReadNonNativeBinaryArrays)");
    return (0);
  }
  for (i = 0; i < layout->n_arrays; i++) {
    array = SDDS_dataset->array + i;
    if (array->definition && !SDDS_FreeArrayDefinition(array->definition)) {
      SDDS_SetError("Unable to get array--array definition corrupted (SDDS_ReadNonNativeBinaryArrays)");
      return (0);
    }
    if (!SDDS_CopyArrayDefinition(&array->definition, layout->array_definition + i)) {
      SDDS_SetError("Unable to read array--definition copy failed (SDDS_ReadNonNativeBinaryArrays)");
      return (0);
    }
    /*if (array->dimension) free(array->dimension); */
    if (!(array->dimension = SDDS_Realloc(array->dimension, sizeof(*array->dimension) * array->definition->dimensions))) {
      SDDS_SetError("Unable to read array--allocation failure (SDDS_ReadNonNativeBinaryArrays)");
      return (0);
    }
#if defined(zLib)
    if (SDDS_dataset->layout.gzipFile) {
      if (!SDDS_GZipBufferedRead(array->dimension, sizeof(*array->dimension) * array->definition->dimensions, gzfp, fBuffer, SDDS_LONG, SDDS_dataset->layout.byteOrderDeclared)) {
        SDDS_SetError("Unable to read arrays--failure reading dimensions (SDDS_ReadNonNativeBinaryArrays)");
        return (0);
      }
    } else {
#endif
      if (SDDS_dataset->layout.lzmaFile) {
        if (!SDDS_LZMABufferedRead(array->dimension, sizeof(*array->dimension) * array->definition->dimensions, lzmafp, fBuffer, SDDS_LONG, SDDS_dataset->layout.byteOrderDeclared)) {
          SDDS_SetError("Unable to read arrays--failure reading dimensions (SDDS_ReadNonNativeBinaryArrays)");
          return (0);
        }
      } else {
        if (!SDDS_BufferedRead(array->dimension, sizeof(*array->dimension) * array->definition->dimensions, fp, fBuffer, SDDS_LONG, SDDS_dataset->layout.byteOrderDeclared)) {
          SDDS_SetError("Unable to read arrays--failure reading dimensions (SDDS_ReadNonNativeBinaryArrays)");
          return (0);
        }
      }
#if defined(zLib)
    }
#endif
    array->elements = 1;
    for (j = 0; j < array->definition->dimensions; j++) {
      SDDS_SwapLong(&(array->dimension[j]));
      array->elements *= array->dimension[j];
    }
    if (array->data)
      free(array->data);
    array->data = array->pointer = NULL;
    if (array->elements == 0)
      continue;
    if (array->elements < 0) {
      SDDS_SetError("Unable to read array--number of elements is negative (SDDS_ReadNonNativeBinaryArrays)");
      return (0);
    }
    if (!(array->data = SDDS_Realloc(array->data, array->elements * SDDS_type_size[array->definition->type - 1]))) {
      SDDS_SetError("Unable to read array--allocation failure (SDDS_ReadNonNativeBinaryArrays)");
      return (0);
    }
    if (array->definition->type == SDDS_STRING) {
#if defined(zLib)
      if (SDDS_dataset->layout.gzipFile) {
        for (j = 0; j < array->elements; j++) {
          if (!(((char **)(array->data))[j] = SDDS_ReadNonNativeGZipBinaryString(gzfp, fBuffer, 0))) {
            SDDS_SetError("Unable to read arrays--failure reading string (SDDS_ReadNonNativeBinaryArrays)");
            return (0);
          }
        }
      } else {
#endif
        if (SDDS_dataset->layout.lzmaFile) {
          for (j = 0; j < array->elements; j++) {
            if (!(((char **)(array->data))[j] = SDDS_ReadNonNativeLZMABinaryString(lzmafp, fBuffer, 0))) {
              SDDS_SetError("Unable to read arrays--failure reading string (SDDS_ReadNonNativeBinaryArrays)");
              return (0);
            }
          }
        } else {
          for (j = 0; j < array->elements; j++) {
            if (!(((char **)(array->data))[j] = SDDS_ReadNonNativeBinaryString(fp, fBuffer, 0))) {
              SDDS_SetError("Unable to read arrays--failure reading string (SDDS_ReadNonNativeBinaryArrays)");
              return (0);
            }
          }
        }
#if defined(zLib)
      }
#endif
    } else {
#if defined(zLib)
      if (SDDS_dataset->layout.gzipFile) {
        if (!SDDS_GZipBufferedRead(array->data, SDDS_type_size[array->definition->type - 1] * array->elements, gzfp, fBuffer, array->definition->type, SDDS_dataset->layout.byteOrderDeclared)) {
          SDDS_SetError("Unable to read arrays--failure reading values (SDDS_ReadNonNativeBinaryArrays)");
          return (0);
        }
      } else {
#endif
        if (SDDS_dataset->layout.lzmaFile) {
          if (!SDDS_LZMABufferedRead(array->data, SDDS_type_size[array->definition->type - 1] * array->elements, lzmafp, fBuffer, array->definition->type, SDDS_dataset->layout.byteOrderDeclared)) {
            SDDS_SetError("Unable to read arrays--failure reading values (SDDS_ReadNonNativeBinaryArrays)");
            return (0);
          }
        } else {
          if (!SDDS_BufferedRead(array->data, SDDS_type_size[array->definition->type - 1] * array->elements, fp, fBuffer, array->definition->type, SDDS_dataset->layout.byteOrderDeclared)) {
            SDDS_SetError("Unable to read arrays--failure reading values (SDDS_ReadNonNativeBinaryArrays)");
            return (0);
          }
        }
#if defined(zLib)
      }
#endif
    }
  }
  SDDS_SwapEndsArrayData(SDDS_dataset);
  return (1);
}

SDDS_ReadNonNativeBinaryPage()

int32_t SDDS_ReadNonNativeBinaryPage	(	SDDS_DATASET *	SDDS_dataset,
		int64_t	sparse_interval,
		int64_t	sparse_offset )

Reads a non-native endian binary page from an SDDS dataset.

This function reads a binary page from the specified SDDS dataset, handling data with non-native endianness. It performs necessary byte order conversions to ensure correct data interpretation on the host system. The function supports sparse reading based on the provided interval and offset.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to read from.
[in]	sparse_interval	Interval between rows to be read for sparsity.
[in]	sparse_offset	Offset to start reading rows for sparsity.

Returns

int32_t Returns the number of rows read on success, or 0 on failure.

Return values

>0	Number of rows successfully read.
0	An error occurred during the read operation, such as I/O failures, data corruption, or unsupported data modes.

Note

This function is a wrapper for SDDS_ReadNonNativeBinaryPageDetailed with specific parameters.

Definition at line 4312 of file SDDS_binary.c.

                                                                                                                 {
  return SDDS_ReadNonNativeBinaryPageDetailed(SDDS_dataset, sparse_interval, sparse_offset, 0);
}

SDDS_ReadNonNativeBinaryParameters()

int32_t SDDS_ReadNonNativeBinaryParameters

(

SDDS_DATASET *

SDDS_dataset

)

Reads non-native endian binary parameters from an SDDS dataset.

This function iterates through all parameter definitions in the specified SDDS dataset and reads their binary data from the underlying file. It handles various data types, including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. For string parameters, it reads each string individually, ensuring proper memory allocation and byte order conversion. Parameters with fixed values are processed by scanning the fixed value strings into the appropriate data types. The function supports different compression formats, including uncompressed, LZMA-compressed, and GZIP-compressed files.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to read from.

Returns

int32_t Returns 1 on successful reading and byte-swapping of all parameters, or 0 if an error occurred.

Return values

1	All non-native endian parameters were successfully read and byte-swapped.
0	An error occurred during the read or byte-swapping process, such as I/O failures, memory allocation issues, or corrupted parameter definitions.

Note

This function modifies the dataset's parameter data in place. It should be called after successfully opening and preparing the dataset for reading. Ensure that the dataset structure is properly initialized to prevent undefined behavior.

Definition at line 4592 of file SDDS_binary.c.

                                                                       {
  int32_t i;
  SDDS_LAYOUT *layout;
  /*  char *predefined_format; */
  char buffer[SDDS_MAXLINE];
#if defined(zLib)
  gzFile gzfp = NULL;
#endif
  FILE *fp = NULL;
  struct lzmafile *lzmafp = NULL;
  SDDS_FILEBUFFER *fBuffer;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReadNonNativeBinaryParameters"))
    return (0);
  layout = &SDDS_dataset->layout;
  if (!layout->n_parameters)
    return (1);
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    gzfp = layout->gzfp;
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      lzmafp = layout->lzmafp;
    } else {
      fp = layout->fp;
    }
#if defined(zLib)
  }
#endif
  fBuffer = &SDDS_dataset->fBuffer;
  for (i = 0; i < layout->n_parameters; i++) {
    if (layout->parameter_definition[i].definition_mode & SDDS_WRITEONLY_DEFINITION)
      continue;
    if (layout->parameter_definition[i].fixed_value) {
      strcpy(buffer, layout->parameter_definition[i].fixed_value);
      if (!SDDS_ScanData(buffer, layout->parameter_definition[i].type, 0, SDDS_dataset->parameter[i], 0, 1)) {
        SDDS_SetError("Unable to read page--parameter scanning error (SDDS_ReadNonNativeBinaryParameters)");
        return (0);
      }
    } else if (layout->parameter_definition[i].type == SDDS_STRING) {
      if (*(char **)SDDS_dataset->parameter[i])
        free(*(char **)SDDS_dataset->parameter[i]);
#if defined(zLib)
      if (SDDS_dataset->layout.gzipFile) {
        if (!(*((char **)SDDS_dataset->parameter[i]) = SDDS_ReadNonNativeGZipBinaryString(gzfp, fBuffer, 0))) {
          SDDS_SetError("Unable to read parameters--failure reading string (SDDS_ReadNonNativeBinaryParameters)");
          return (0);
        }
      } else {
#endif
        if (SDDS_dataset->layout.lzmaFile) {
          if (!(*((char **)SDDS_dataset->parameter[i]) = SDDS_ReadNonNativeLZMABinaryString(lzmafp, fBuffer, 0))) {
            SDDS_SetError("Unable to read parameters--failure reading string (SDDS_ReadNonNativeBinaryParameters)");
            return (0);
          }
        } else {
          if (!(*((char **)SDDS_dataset->parameter[i]) = SDDS_ReadNonNativeBinaryString(fp, fBuffer, 0))) {
            SDDS_SetError("Unable to read parameters--failure reading string (SDDS_ReadNonNativeBinaryParameters)");
            return (0);
          }
        }
#if defined(zLib)
      }
#endif
    } else {
#if defined(zLib)
      if (SDDS_dataset->layout.gzipFile) {
        if (!SDDS_GZipBufferedRead(SDDS_dataset->parameter[i], SDDS_type_size[layout->parameter_definition[i].type - 1], gzfp, fBuffer, layout->parameter_definition[i].type, SDDS_dataset->layout.byteOrderDeclared)) {
          SDDS_SetError("Unable to read parameters--failure reading value (SDDS_ReadNonNativeBinaryParameters)");
          return (0);
        }
      } else {
#endif
        if (SDDS_dataset->layout.lzmaFile) {
          if (!SDDS_LZMABufferedRead(SDDS_dataset->parameter[i], SDDS_type_size[layout->parameter_definition[i].type - 1], lzmafp, fBuffer, layout->parameter_definition[i].type, SDDS_dataset->layout.byteOrderDeclared)) {
            SDDS_SetError("Unable to read parameters--failure reading value (SDDS_ReadNonNativeBinaryParameters)");
            return (0);
          }
        } else {
          if (!SDDS_BufferedRead(SDDS_dataset->parameter[i], SDDS_type_size[layout->parameter_definition[i].type - 1], fp, fBuffer, layout->parameter_definition[i].type, SDDS_dataset->layout.byteOrderDeclared)) {
            SDDS_SetError("Unable to read parameters--failure reading value (SDDS_ReadNonNativeBinaryParameters)");
            return (0);
          }
        }
#if defined(zLib)
      }
#endif
    }
  }
  SDDS_SwapEndsParameterData(SDDS_dataset);
  return (1);
}

SDDS_ReadNonNativeBinaryRow()

int32_t SDDS_ReadNonNativeBinaryRow	(	SDDS_DATASET *	SDDS_dataset,
		int64_t	row,
		int32_t	skip )

Reads a non-native endian binary row from an SDDS dataset.

This function reads a single row of data from the specified SDDS dataset, handling data with non-native endianness. It iterates through all column definitions and reads each column's data for the given row. For string columns, it ensures proper memory allocation and byte order conversion. For other data types, it reads the binary data and performs necessary byte swapping. The function supports different compression formats, including uncompressed, LZMA-compressed, and GZIP-compressed files.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to read from.
[in]	row	The index of the row to read.
[in]	skip	If non-zero, the function will skip reading the row data, useful for sparse reading.

Returns

int32_t Returns 1 on successful reading of the row, or 0 if an error occurred.

Return values

1	The row was successfully read and byte-swapped.
0	An error occurred during the read or byte-swapping process, such as I/O failures or corrupted data.

Note

This function modifies the dataset's data in place. It should be called after successfully opening and preparing the dataset for reading. Ensure that the dataset structure is properly initialized to prevent undefined behavior.

Definition at line 4878 of file SDDS_binary.c.

                                                                                           {
  int64_t i, type, size;
  SDDS_LAYOUT *layout;
#if defined(zLib)
  gzFile gzfp;
#endif
  FILE *fp;
  struct lzmafile *lzmafp;
  SDDS_FILEBUFFER *fBuffer;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReadNonNativeBinaryRow"))
    return (0);
  layout = &SDDS_dataset->layout;
  fBuffer = &SDDS_dataset->fBuffer;
 
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    gzfp = layout->gzfp;
    for (i = 0; i < layout->n_columns; i++) {
      if (layout->column_definition[i].definition_mode & SDDS_WRITEONLY_DEFINITION)
        continue;
      if ((type = layout->column_definition[i].type) == SDDS_STRING) {
        if (!skip) {
          if (((char ***)SDDS_dataset->data)[i][row])
            free((((char ***)SDDS_dataset->data)[i][row]));
          if (!(((char ***)SDDS_dataset->data)[i][row] = SDDS_ReadNonNativeGZipBinaryString(gzfp, fBuffer, 0))) {
            SDDS_SetError("Unable to read rows--failure reading string (SDDS_ReadNonNativeBinaryRow)");
            return (0);
          }
        } else {
          if (!SDDS_ReadNonNativeGZipBinaryString(gzfp, fBuffer, 1)) {
            SDDS_SetError("Unable to read rows--failure reading string (SDDS_ReadNonNativeBinaryRow)");
            return 0;
          }
        }
      } else {
        size = SDDS_type_size[type - 1];
        if (!SDDS_GZipBufferedRead(skip ? NULL : (char *)SDDS_dataset->data[i] + row * size, size, gzfp, fBuffer, type, SDDS_dataset->layout.byteOrderDeclared)) {
          SDDS_SetError("Unable to read row--failure reading value (SDDS_ReadNonNativeBinaryRow)");
          return (0);
        }
      }
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      lzmafp = layout->lzmafp;
      for (i = 0; i < layout->n_columns; i++) {
        if (layout->column_definition[i].definition_mode & SDDS_WRITEONLY_DEFINITION)
          continue;
        if ((type = layout->column_definition[i].type) == SDDS_STRING) {
          if (!skip) {
            if (((char ***)SDDS_dataset->data)[i][row])
              free((((char ***)SDDS_dataset->data)[i][row]));
            if (!(((char ***)SDDS_dataset->data)[i][row] = SDDS_ReadNonNativeLZMABinaryString(lzmafp, fBuffer, 0))) {
              SDDS_SetError("Unable to read rows--failure reading string (SDDS_ReadNonNativeBinaryRow)");
              return (0);
            }
          } else {
            if (!SDDS_ReadNonNativeLZMABinaryString(lzmafp, fBuffer, 1)) {
              SDDS_SetError("Unable to read rows--failure reading string (SDDS_ReadNonNativeBinaryRow)");
              return 0;
            }
          }
        } else {
          size = SDDS_type_size[type - 1];
          if (!SDDS_LZMABufferedRead(skip ? NULL : (char *)SDDS_dataset->data[i] + row * size, size, lzmafp, fBuffer, type, SDDS_dataset->layout.byteOrderDeclared)) {
            SDDS_SetError("Unable to read row--failure reading value (SDDS_ReadNonNativeBinaryRow)");
            return (0);
          }
        }
      }
    } else {
      fp = layout->fp;
      for (i = 0; i < layout->n_columns; i++) {
        if (layout->column_definition[i].definition_mode & SDDS_WRITEONLY_DEFINITION)
          continue;
        if ((type = layout->column_definition[i].type) == SDDS_STRING) {
          if (!skip) {
            if (((char ***)SDDS_dataset->data)[i][row])
              free((((char ***)SDDS_dataset->data)[i][row]));
            if (!(((char ***)SDDS_dataset->data)[i][row] = SDDS_ReadNonNativeBinaryString(fp, fBuffer, 0))) {
              SDDS_SetError("Unable to read rows--failure reading string (SDDS_ReadNonNativeBinaryRow)");
              return (0);
            }
          } else {
            if (!SDDS_ReadNonNativeBinaryString(fp, fBuffer, 1)) {
              SDDS_SetError("Unable to read rows--failure reading string (SDDS_ReadNonNativeBinaryRow)");
              return 0;
            }
          }
        } else {
          size = SDDS_type_size[type - 1];
          if (!SDDS_BufferedRead(skip ? NULL : (char *)SDDS_dataset->data[i] + row * size, size, fp, fBuffer, type, SDDS_dataset->layout.byteOrderDeclared)) {
            SDDS_SetError("Unable to read row--failure reading value (SDDS_ReadNonNativeBinaryRow)");
            return (0);
          }
        }
      }
    }
#if defined(zLib)
  }
#endif
  return (1);
}

SDDS_ReadNonNativeBinaryString()

char * SDDS_ReadNonNativeBinaryString	(	FILE *	fp,
		SDDS_FILEBUFFER *	fBuffer,
		int32_t	skip )

Reads a non-native endian binary string from a file.

This function reads a binary string from the specified file pointer, handling non-native endianness. It first reads the length of the string, swaps its byte order if necessary, allocates memory for the string, reads the string data, and null-terminates it.

Parameters

[in]	fp	Pointer to the FILE from which to read the string.
[in,out]	fBuffer	Pointer to the SDDS_FILEBUFFER structure used for buffered reading.
[in]	skip	If non-zero, the function will skip reading the string data, useful for sparse reading.

Returns

char* Returns a pointer to the read string on success, or NULL if an error occurred.

Return values

Non-NULL	Pointer to the newly allocated string.
NULL	An error occurred during reading or memory allocation.

Note

The caller is responsible for freeing the returned string to prevent memory leaks.

Definition at line 5001 of file SDDS_binary.c.

                                                                                       {
  int32_t length;
  char *string;
 
  if (!SDDS_BufferedRead(&length, sizeof(length), fp, fBuffer, SDDS_LONG, 0))
    return (0);
  SDDS_SwapLong(&length);
  if (length < 0)
    return (0);
  if (!(string = SDDS_Malloc(sizeof(*string) * (length + 1))))
    return (NULL);
  if (length && !SDDS_BufferedRead(skip ? NULL : string, sizeof(*string) * length, fp, fBuffer, SDDS_STRING, 0))
    return (NULL);
  string[length] = 0;
  return (string);
}

SDDS_ReadNonNativePage()

epicsShareFuncSDDS int32_t SDDS_ReadNonNativePage ( SDDS_DATASET * SDDS_dataset )

extern

Reads a non-native endian page from an SDDS dataset.

This function reads a page of data from the specified SDDS dataset, handling data with non-native endianness. It supports both ASCII and binary data modes, performing necessary byte order conversions to ensure correct data interpretation on the host system.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to read from.

Returns

int32_t Returns the number of rows read on success, or 0 on failure.

Return values

>0	Number of rows successfully read.
0	An error occurred during the read operation, such as I/O failures, data corruption, or unsupported data modes.

Note

This function is a wrapper for SDDS_ReadNonNativePageDetailed with default parameters. It should be used when no specific mode, sparse interval, or offset is required.

Definition at line 4133 of file SDDS_binary.c.

                                                           {
  return SDDS_ReadNonNativePageDetailed(SDDS_dataset, 0, 1, 0, 0);
}

SDDS_ReadNonNativePageSparse()

int32_t SDDS_ReadNonNativePageSparse	(	SDDS_DATASET *	SDDS_dataset,
		uint32_t	mode,
		int64_t	sparse_interval,
		int64_t	sparse_offset )

Reads a sparse non-native endian page from an SDDS dataset.

This function reads a sparse page of data from the specified SDDS dataset, handling data with non-native endianness. Sparse reading allows for selective row retrieval based on the provided interval and offset.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to read from.
[in]	mode	Mode flag to support future expansion.
[in]	sparse_interval	Interval between rows to be read for sparsity.
[in]	sparse_offset	Offset to start reading rows for sparsity.

Returns

int32_t Returns the number of rows read on success, or 0 on failure.

Return values

>0	Number of rows successfully read.
0	An error occurred during the read operation, such as I/O failures, data corruption, or unsupported data modes.

Note

This function is a wrapper for SDDS_ReadNonNativePageDetailed with specific parameters to enable sparse reading. It should be used when selective row retrieval is desired.

Definition at line 4155 of file SDDS_binary.c.

                                                                                                                                {
  return SDDS_ReadNonNativePageDetailed(SDDS_dataset, mode, sparse_interval, sparse_offset, 0);
}

SDDS_ReadPage()

epicsShareFuncSDDS int32_t SDDS_ReadPage ( SDDS_DATASET * SDDS_dataset )

extern

Reads a page of an SDDS file. Usually called after SDDS_InitializeInput.

Parameters

SDDS_dataset

Address of the SDDS_DATASET structure for the data set.

Returns

Page number on success, -1 if it is the end-of-file, 0 on error.

Definition at line 1007 of file SDDS_input.c.

                                                  {
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io)
    return SDDS_MPI_ReadPage(SDDS_dataset);
#endif
  return SDDS_ReadPageSparse(SDDS_dataset, 0, 1, 0, 0);
}

SDDS_ReadPageLastRows()

epicsShareFuncSDDS int32_t SDDS_ReadPageLastRows ( SDDS_DATASET * SDDS_dataset, int64_t last_rows )

extern

Reads the last specified number of rows from the SDDS dataset.

Parameters

SDDS_dataset	The pointer to the SDDS dataset structure.
last_rows	The number of rows to read from the end of the dataset.

Returns

Page number on success, -1 if it is the end-of-file, 0 on error.

Definition at line 1157 of file SDDS_input.c.

                                                                             {
  int32_t retval;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReadPageLastRows"))
    return (0);
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't read page--file is disconnected (SDDS_ReadPageLastRows)");
    return 0;
  }
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!SDDS_dataset->layout.gzfp) {
      SDDS_SetError("Unable to read page--NULL file pointer (SDDS_ReadPageLastRows)");
      return (0);
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!SDDS_dataset->layout.lzmafp) {
        SDDS_SetError("Unable to read page--NULL file pointer (SDDS_ReadPageLastRows)");
        return (0);
      }
    } else {
      if (!SDDS_dataset->layout.fp) {
        SDDS_SetError("Unable to read page--NULL file pointer (SDDS_ReadPageLastRows)");
        return (0);
      }
    }
#if defined(zLib)
  }
#endif
  if (SDDS_dataset->original_layout.data_mode.mode == SDDS_ASCII) {
    if ((retval = SDDS_ReadAsciiPageLastRows(SDDS_dataset, last_rows)) < 1) {
      return (retval);
    }
  } else if (SDDS_dataset->original_layout.data_mode.mode == SDDS_BINARY) {
    if ((retval = SDDS_ReadBinaryPageLastRows(SDDS_dataset, last_rows)) < 1) {
      return (retval);
    }
  } else {
    SDDS_SetError("Unable to read page--unrecognized data mode (SDDS_ReadPageLastRows)");
    return (0);
  }
  if (!SDDS_dataset->layout.gzipFile && !SDDS_dataset->layout.lzmaFile && !SDDS_dataset->layout.popenUsed && SDDS_dataset->layout.filename && SDDS_dataset->pagecount_offset) {
    /* Data is not:
         1. from a gzip file
         2. from a file that is being internally decompressed by a command executed with popen()
         3. from a pipe set up externally (e.g., -pipe=in on commandline)
         and pagecount_offset has been allocate memory from SDDS_initializeInput()
      */
    if (SDDS_dataset->pagecount_offset[SDDS_dataset->pages_read] < SDDS_dataset->endOfFile_offset) {
      SDDS_dataset->pages_read++;
      if (!(SDDS_dataset->pagecount_offset = realloc(SDDS_dataset->pagecount_offset, sizeof(int64_t) * (SDDS_dataset->pages_read + 1)))) {
        SDDS_SetError("Unable to allocate memory for pagecount_offset (SDDS_ReadPageLastRows)");
        exit(1);
      }
      SDDS_dataset->pagecount_offset[SDDS_dataset->pages_read] = ftell(SDDS_dataset->layout.fp);
    }
  } else {
    SDDS_dataset->pages_read++;
  }
  return (retval);
}

SDDS_ReadPageSparse()

epicsShareFuncSDDS int32_t SDDS_ReadPageSparse ( SDDS_DATASET * SDDS_dataset, uint32_t mode, int64_t sparse_interval, int64_t sparse_offset, int32_t sparse_statistics )

extern

Reads a sparsed page of an SDDS file. Usually called after SDDS_InitializeInput.

Parameters

SDDS_dataset	A pointer to an SDDS dataset.
mode	Not used.
sparse_interval	The column data can be sparsified over row intervals if this is greater than 1.
sparse_offset	This is used to skip the initial rows of the column data.
sparse_statistics	Not used.

Returns

Page number on success, -1 if it is the end-of-file, 0 on error.

Definition at line 1083 of file SDDS_input.c.

{
  int32_t retval;
  /*  SDDS_LAYOUT layout_copy; */
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReadPageSparse"))
    return (0);
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't read page--file is disconnected (SDDS_ReadPageSparse)");
    return 0;
  }
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!SDDS_dataset->layout.gzfp) {
      SDDS_SetError("Unable to read page--NULL file pointer (SDDS_ReadPageSparse)");
      return (0);
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!SDDS_dataset->layout.lzmafp) {
        SDDS_SetError("Unable to read page--NULL file pointer (SDDS_ReadPageSparse)");
        return (0);
      }
    } else {
      if (!SDDS_dataset->layout.fp) {
        SDDS_SetError("Unable to read page--NULL file pointer (SDDS_ReadPageSparse)");
        return (0);
      }
    }
#if defined(zLib)
  }
#endif
  if (SDDS_dataset->original_layout.data_mode.mode == SDDS_ASCII) {
    if ((retval = SDDS_ReadAsciiPage(SDDS_dataset, sparse_interval, sparse_offset, sparse_statistics)) < 1) {
      return (retval);
    }
  } else if (SDDS_dataset->original_layout.data_mode.mode == SDDS_BINARY) {
    if ((retval = SDDS_ReadBinaryPage(SDDS_dataset, sparse_interval, sparse_offset, sparse_statistics)) < 1) {
      return (retval);
    }
  } else {
    SDDS_SetError("Unable to read page--unrecognized data mode (SDDS_ReadPageSparse)");
    return (0);
  }
  if (!SDDS_dataset->layout.gzipFile && !SDDS_dataset->layout.lzmaFile && !SDDS_dataset->layout.popenUsed && SDDS_dataset->layout.filename && SDDS_dataset->pagecount_offset) {
    /* Data is not:
         1. from a gzip file
         2. from a file that is being internally decompressed by a command executed with popen()
         3. from a pipe set up externally (e.g., -pipe=in on commandline)
         and pagecount_offset has been allocate memory from SDDS_initializeInput()
      */
    if (SDDS_dataset->pagecount_offset[SDDS_dataset->pages_read] < SDDS_dataset->endOfFile_offset) {
      SDDS_dataset->pages_read++;
      if (!(SDDS_dataset->pagecount_offset = realloc(SDDS_dataset->pagecount_offset, sizeof(int64_t) * (SDDS_dataset->pages_read + 1)))) {
        SDDS_SetError("Unable to allocate memory for pagecount_offset (SDDS_ReadPageSparse)");
        exit(1);
      }
      SDDS_dataset->pagecount_offset[SDDS_dataset->pages_read] = ftell(SDDS_dataset->layout.fp);
    }
  } else {
    SDDS_dataset->pages_read++;
  }
  return (retval);
}

SDDS_ReadRecoveryPossible()

epicsShareFuncSDDS int32_t SDDS_ReadRecoveryPossible ( SDDS_DATASET * SDDS_dataset )

extern

Checks if any data in an SDDS page was recovered after an error was detected.

This function inspects the SDDS dataset to determine if any data recovery was possible following an error during data reading. It resets the recovery flag after checking.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• Returns 1 if recovery was possible.
• Returns 0 if no recovery was performed or if recovery was not possible.

The function performs the following steps:

• Retrieves the current state of the readRecoveryPossible flag from the dataset.
• Resets the readRecoveryPossible flag to 0.
• Returns the original state of the readRecoveryPossible flag.

Note

• This function is typically used after attempting to recover from a read error to verify if any partial data was successfully recovered.
• The recovery flag is automatically managed by other functions within the SDDS library.

Definition at line 2075 of file SDDS_binary.c.

                                                              {
  int32_t returnValue;
 
  returnValue = SDDS_dataset->readRecoveryPossible;
  SDDS_dataset->readRecoveryPossible = 0;
  return returnValue;
}

SDDS_Realloc()

epicsShareFuncSDDS void * SDDS_Realloc ( void * old_ptr, size_t new_size )

extern

Reallocates memory to a new size.

This function extends the standard realloc functionality by zero-initializing any newly allocated memory beyond the original size. It ensures that memory is consistently reallocated and initialized across different build configurations.

Parameters

[in]	old_ptr	Pointer to the original memory block. If NULL, the function behaves like SDDS_Malloc.
[in]	new_size	New size in bytes for the memory block.

Returns

Pointer to the reallocated memory block with the new size. If new_size is less than or equal to zero, a minimum of 4 bytes is allocated. Returns NULL if memory reallocation fails.

See also

SDDS_Malloc

SDDS_Free

Definition at line 743 of file SDDS_utils.c.

                                                   {
  /* this is required because some realloc's don't behave properly when asked to return a
   * pointer to 0 memory.  They return NULL.
   */
  if (new_size <= 0)
    new_size = 4;
  /* this is required because some realloc's don't behave properly when given a NULL pointer */
  if (!old_ptr)
    return (SDDS_Malloc(new_size));
  else
    return (realloc(old_ptr, new_size));
}

SDDS_ReconnectFile()

epicsShareFuncSDDS int32_t SDDS_ReconnectFile ( SDDS_DATASET * SDDS_dataset )

extern

Reconnects the SDDS dataset to its previously associated file.

This function re-establishes the connection between the SDDS dataset and the file it was previously linked to before being disconnected. It opens the file in read/write mode, seeks to the appropriate position, and updates the dataset's internal state to reflect that it is connected.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure to be reconnected.

Returns

• 1 on successful reconnection.
• 0 if an error occurred during reconnection. In this case, an error message is set internally.

Precondition

• The dataset must have been previously disconnected using SDDS_DisconnectFile.
• The dataset must have a valid filename set.

Note

• Reconnection will fail if the file is not accessible or if the dataset was not properly disconnected.

Warning

• Ensure that the file has not been modified externally in a way that could disrupt the dataset's state.

Definition at line 127 of file SDDS_output.c.

                                                       {
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io)
    return SDDS_MPI_ReconnectFile(SDDS_dataset);
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReconnectFile"))
    return 0;
  if (!SDDS_dataset->layout.disconnected || !SDDS_dataset->layout.filename) {
    SDDS_SetError("Can't reconnect file.  Not disconnected or missing filename. (SDDS_ReconnectFile)");
    return 0;
  }
  if (!(SDDS_dataset->layout.fp = fopen(SDDS_dataset->layout.filename, FOPEN_READ_AND_WRITE_MODE))) {
    char s[1024];
    sprintf(s, "Unable to open file %s (SDDS_ReconnectFile)", SDDS_dataset->layout.filename);
    SDDS_SetError(s);
    return 0;
  }
  if (fseek(SDDS_dataset->layout.fp, 0, 2) == -1) {
    SDDS_SetError("Can't reconnect file.  Fseek failed. (SDDS_ReconnectFile)");
    return 0;
  }
  SDDS_dataset->original_layout.fp = SDDS_dataset->layout.fp;
  SDDS_dataset->layout.disconnected = 0;
  return 1;
}

SDDS_ReconnectInputFile()

epicsShareFuncSDDS int32_t SDDS_ReconnectInputFile ( SDDS_DATASET * SDDS_dataset, long position )

extern

Reconnects the input file for the SDDS dataset at a specified position.

This function re-establishes the connection between the SDDS dataset and its input file, positioning the file pointer at the specified byte offset. This allows the dataset to resume reading from a specific location within the input file.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure to reconnect.
[in]	position	The byte offset position in the input file where reconnection should occur.

Returns

• 1 on successful reconnection.
• 0 on failure. In this case, an internal error message is set.

Precondition

• The dataset must have been previously disconnected using SDDS_DisconnectInputFile.
• The dataset must have a valid filename set.
• The specified position must be valid within the input file.

Note

• Reconnection will fail if the input file is compressed (gzip, lzma, xz).
• The function seeks to the specified position after opening the file.

Warning

• Ensure that the specified position does not disrupt the dataset's data integrity.

Definition at line 230 of file SDDS_output.c.

                                                                           {
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io) {
    SDDS_SetError("Error: MPI mode not supported yet in SDDS_ReconnectInputFile");
    return 0;
  }
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ReconnectInputFile"))
    return 0;
  if (!SDDS_dataset->layout.disconnected || !SDDS_dataset->layout.filename) {
    SDDS_SetError("Can't reconnect file.  Not disconnected or missing filename. (SDDS_ReconnectInputFile)");
    return 0;
  }
  if (!(SDDS_dataset->layout.fp = fopen(SDDS_dataset->layout.filename, FOPEN_READ_MODE))) {
    char s[1024];
    sprintf(s, "Unable to open file %s (SDDS_ReconnectInputFile)", SDDS_dataset->layout.filename);
    SDDS_SetError(s);
    return 0;
  }
  if (fseek(SDDS_dataset->layout.fp, position, SEEK_SET) == -1) {
    SDDS_SetError("Can't reconnect file.  Fseek failed. (SDDS_ReconnectInputFile)");
    return 0;
  }
  SDDS_dataset->original_layout.fp = SDDS_dataset->layout.fp;
  SDDS_dataset->layout.disconnected = 0;
  return 1;
}

SDDS_RegisterProgramName()

epicsShareFuncSDDS void SDDS_RegisterProgramName ( const char * name )

extern

Registers the executable program name for use in error messages.

This function stores the name of the executing program, which is included in various error and warning messages generated by the SDDS library routines.

Parameters

[in]

name

The name of the program. If NULL, the registered program name is cleared.

Note

This function should be called at the beginning of the program to provide context in error messages.

See also

SDDS_Bomb

SDDS_Warning

Definition at line 318 of file SDDS_utils.c.

                                                {
  char *newProgramName = NULL;
 
  if (name) {
    if (!(newProgramName = SDDS_DuplicateProgramName(name)))
      return;
  }
  mdb_thread_lock(&registeredProgramNameLock);
  free(registeredProgramName);
  registeredProgramName = newProgramName;
  mdb_thread_unlock(&registeredProgramNameLock);
}

SDDS_RemovePadding()

epicsShareFuncSDDS void SDDS_RemovePadding ( char * s )

extern

Removes leading and trailing whitespace from a string.

This function trims all leading and trailing whitespace characters from the input string s. It modifies the string in place, ensuring that any padding spaces are removed while preserving the internal content.

Parameters

[in,out]

s

Pointer to the null-terminated string to be trimmed. The string will be modified in place.

Note

The function handles all standard whitespace characters as defined by the isspace function. If the string consists entirely of whitespace, the function will result in an empty string.

See also

isspace

Definition at line 2445 of file SDDS_utils.c.

                                 {
  char *ptr;
  ptr = s;
  while (isspace(*ptr))
    ptr++;
  if (ptr != s)
    strcpy(s, ptr);
  ptr = s + strlen(s) - 1;
  while (isspace(*ptr))
    *ptr-- = 0;
}

SDDS_RestoreLayout()

epicsShareFuncSDDS int32_t SDDS_RestoreLayout ( SDDS_DATASET * SDDS_dataset )

extern

Restores a previously saved layout of the SDDS_DATASET.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure whose layout is to be restored.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 697 of file SDDS_copy.c.

                                                       {
  SDDS_LAYOUT *source, *target;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_RestoreLayout"))
    return (0);
 
  source = &SDDS_dataset->original_layout;
  target = &SDDS_dataset->layout;
 
  /* copy pointer elements of structure into new memory */
  if (source->n_columns) {
    if (target->column_definition == source->column_definition) {
      SDDS_SetError("Unable to restore layout--column definition pointers are the same  (SDDS_RestoreLayout)");
      return (0);
    }
    if (!(target->column_definition = (COLUMN_DEFINITION *)SDDS_Realloc((void *)target->column_definition, sizeof(COLUMN_DEFINITION) * source->n_columns))) {
      SDDS_SetError("Unable to restore layout--allocation failure (SDDS_RestoreLayout)");
      return (0);
    }
    memcpy((char *)target->column_definition, (char *)source->column_definition, sizeof(COLUMN_DEFINITION) * source->n_columns);
  }
  if (source->n_parameters) {
    if (target->parameter_definition == source->parameter_definition) {
      SDDS_SetError("Unable to restore layout--parameter definition pointers are the same  (SDDS_RestoreLayout)");
      return (0);
    }
    if (!(target->parameter_definition = (PARAMETER_DEFINITION *)SDDS_Realloc((void *)target->parameter_definition, sizeof(PARAMETER_DEFINITION) * source->n_parameters))) {
      SDDS_SetError("Unable to restore layout--allocation failure (SDDS_RestoreLayout)");
      return (0);
    }
    memcpy((char *)target->parameter_definition, (char *)source->parameter_definition, sizeof(PARAMETER_DEFINITION) * source->n_parameters);
  }
  if (source->n_arrays) {
    if (target->array_definition == source->array_definition) {
      SDDS_SetError("Unable to restore layout--array definition pointers are the same  (SDDS_RestoreLayout)");
      return (0);
    }
    if (!(target->array_definition = (ARRAY_DEFINITION *)SDDS_Realloc((void *)target->array_definition, sizeof(ARRAY_DEFINITION) * source->n_arrays))) {
      SDDS_SetError("Unable to restore layout--allocation failure (SDDS_RestoreLayout)");
      return (0);
    }
    memcpy((char *)target->array_definition, (char *)source->array_definition, sizeof(ARRAY_DEFINITION) * source->n_arrays);
  }
  if (source->n_associates) {
    if (target->associate_definition == source->associate_definition) {
      SDDS_SetError("Unable to restore layout--associate definition pointers are the same  (SDDS_RestoreLayout)");
      return (0);
    }
    if (!(target->associate_definition = (ASSOCIATE_DEFINITION *)SDDS_Realloc((void *)target->associate_definition, sizeof(ASSOCIATE_DEFINITION) * source->n_associates))) {
      SDDS_SetError("Unable to restore layout--allocation failure (SDDS_RestoreLayout)");
      return (0);
    }
    memcpy((char *)target->associate_definition, (char *)source->associate_definition, sizeof(ASSOCIATE_DEFINITION) * source->n_associates);
  }
 
  target->n_columns = source->n_columns;
  target->n_parameters = source->n_parameters;
  target->n_associates = source->n_associates;
  target->n_arrays = source->n_arrays;
  target->description = source->description;
  target->contents = source->contents;
  target->version = source->version;
  target->data_mode = source->data_mode;
  target->filename = source->filename;
  target->fp = source->fp;
 
  return (1);
}

SDDS_SaveLayout()

epicsShareFuncSDDS int32_t SDDS_SaveLayout ( SDDS_DATASET * SDDS_dataset )

extern

Saves the current layout of the SDDS_DATASET. The layout is stored internally for future restoration if needed.

Parameters

SDDS_dataset

Pointer to the SDDS_DATASET structure whose layout is to be saved.

Returns

Returns 1 on success; 0 on failure, with an error message recorded.

Definition at line 615 of file SDDS_copy.c.

                                                    {
  SDDS_LAYOUT *source, *target;
 
  if (SDDS_dataset->deferSavingLayout)
    return 1;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SaveLayout"))
    return (0);
 
  if ((source = &SDDS_dataset->layout) == (target = &SDDS_dataset->original_layout)) {
    SDDS_SetError("\"original\" and working page layouts share memory!");
    SDDS_PrintErrors(stderr, SDDS_EXIT_PrintErrors | SDDS_VERBOSE_PrintErrors);
  }
 
  /* copy pointer elements of structure into new memory */
  if (source->n_columns) {
    if (!(target->column_definition = (COLUMN_DEFINITION *)SDDS_Realloc((void *)target->column_definition, sizeof(COLUMN_DEFINITION) * source->n_columns)) || !(target->column_index = (SORTED_INDEX **)SDDS_Realloc((void *)target->column_index, sizeof(SORTED_INDEX *) * source->n_columns))) {
      SDDS_SetError("Unable to save layout--allocation failure (SDDS_SaveLayout)");
      return (0);
    }
    memcpy((char *)target->column_definition, (char *)source->column_definition, sizeof(COLUMN_DEFINITION) * source->n_columns);
    memcpy((char *)target->column_index, (char *)source->column_index, sizeof(SORTED_INDEX *) * source->n_columns);
  }
  if (source->n_parameters) {
    if (!(target->parameter_definition =
            (PARAMETER_DEFINITION *)SDDS_Realloc((void *)target->parameter_definition, sizeof(PARAMETER_DEFINITION) * source->n_parameters)) ||
        !(target->parameter_index = (SORTED_INDEX **)SDDS_Realloc((void *)target->parameter_index, sizeof(SORTED_INDEX *) * source->n_parameters))) {
      SDDS_SetError("Unable to save layout--allocation failure (SDDS_SaveLayout)");
      return (0);
    }
    memcpy((char *)target->parameter_definition, (char *)source->parameter_definition, sizeof(PARAMETER_DEFINITION) * source->n_parameters);
    memcpy((char *)target->parameter_index, (char *)source->parameter_index, sizeof(SORTED_INDEX *) * source->n_parameters);
  }
  if (source->n_arrays) {
    if (!(target->array_definition = (ARRAY_DEFINITION *)SDDS_Realloc((void *)target->array_definition, sizeof(ARRAY_DEFINITION) * source->n_arrays)) || !(target->array_index = (SORTED_INDEX **)SDDS_Realloc((void *)target->array_index, sizeof(SORTED_INDEX *) * source->n_arrays))) {
      SDDS_SetError("Unable to save layout--allocation failure (SDDS_SaveLayout)");
      return (0);
    }
    memcpy((char *)target->array_definition, (char *)source->array_definition, sizeof(ARRAY_DEFINITION) * source->n_arrays);
    memcpy((char *)target->array_index, (char *)source->array_index, sizeof(SORTED_INDEX *) * source->n_arrays);
  }
  if (source->n_associates) {
    if (!(target->associate_definition = (ASSOCIATE_DEFINITION *)SDDS_Realloc((void *)target->associate_definition, sizeof(ASSOCIATE_DEFINITION) * source->n_associates))) {
      SDDS_SetError("Unable to save layout--allocation failure (SDDS_SaveLayout)");
      return (0);
    }
    memcpy((char *)target->associate_definition, (char *)source->associate_definition, sizeof(ASSOCIATE_DEFINITION) * source->n_associates);
  }
 
  target->n_columns = source->n_columns;
  target->n_parameters = source->n_parameters;
  target->n_associates = source->n_associates;
  target->n_arrays = source->n_arrays;
  target->description = source->description;
  target->contents = source->contents;
  target->version = source->version;
  target->data_mode = source->data_mode;
  target->filename = source->filename;
  target->fp = source->fp;
  target->popenUsed = source->popenUsed;
 
  if (SDDS_dataset->layout.n_columns) {
    if (!(SDDS_dataset->column_track_memory = (short *)SDDS_Realloc(SDDS_dataset->column_track_memory, sizeof(short) * SDDS_dataset->layout.n_columns))) {
      SDDS_SetError("memory allocation failure (SDDS_SaveLayout)");
      return(0);
    }
    if (!SDDS_SetMemory(SDDS_dataset->column_track_memory, SDDS_dataset->layout.n_columns, SDDS_SHORT, (short)1, (short)0)) {
      SDDS_SetError("Unable to initialize memory (SDDS_SaveLayout)");
      return (0);
    }
  }
 
  return (1);
}

SDDS_ScanData()

epicsShareFuncSDDS int32_t SDDS_ScanData ( char * string, int32_t type, int32_t field_length, void * data, int64_t index, int32_t is_parameter )

extern

Scans a string and saves the parsed value into a data pointer according to the specified data type.

This function extracts data from a string and stores it in the provided data pointer. It handles various SDDS data types, including integers, floating-point numbers, strings, and characters. The function supports both fixed-field and variable-field formats and can process parameters and column data.

Parameters

string	Pointer to the input string containing the data to be scanned.
type	The SDDS data type to interpret the scanned data as. Valid types include: SDDS_SHORT SDDS_USHORT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_FLOAT SDDS_DOUBLE SDDS_LONGDOUBLE SDDS_STRING SDDS_CHARACTER
field_length	Field length for fixed-field formats. Set to 0 for variable-field formats. If negative, indicates left-padding should be removed.
data	Void pointer to the data storage where the scanned value will be saved. Must be pre-allocated and appropriate for the specified data type.
index	The index within the data array where the value should be stored.
is_parameter	Set to 1 if the data is from an SDDS parameter; set to 0 for column data.

Returns

Returns 1 on success, or 0 on error. If an error occurs, an error message is set via SDDS_SetError().

Note

The function allocates a buffer internally to process the input string. It handles escape sequences for strings and characters using SDDS_InterpretEscapes(). For string data types, the function manages memory allocation for the data array elements.

Definition at line 1748 of file SDDS_ascii.c.

                                                                                                                         {
  char *buffer = NULL;
  int32_t abs_field_length, length;
  int32_t bufferSize = 0;
 
  abs_field_length = abs(field_length);
  if (!string) {
    SDDS_SetError("Unable to scan data--input string is NULL (SDDS_ScanData)");
    return (0);
  }
  if (!data) {
    SDDS_SetError("Unable to scan data--data pointer is NULL (SDDS_ScanData)");
    return (0);
  }
  if (!(buffer = SDDS_Malloc(sizeof(*buffer) * (bufferSize = SDDS_MAXLINE)))) {
    SDDS_SetError("Unable to scan data--allocation failure (SDDS_ScanData)");
    return (0);
  }
  if ((length = strlen(string)) < abs_field_length)
    length = abs_field_length;
  if (bufferSize <= length) {
    if (!(buffer = SDDS_Realloc(buffer, sizeof(*buffer) * (bufferSize = 2 * length)))) {
      /* I allocate 2*length in the hopes that I won't need to realloc too often if I do this */
      SDDS_SetError("Unable to scan data--allocation failure (SDDS_ScanData)");
      return (0);
    }
  }
  if (type != SDDS_STRING) {
    /* for non-string data, fill buffer with string to be scanned */
    if (field_length) {
      /* fill with fixed number of characters */
      if (abs_field_length > (int32_t)strlen(string)) {
        strcpy(buffer, string);
        *string = 0;
      } else {
        strncpy(buffer, string, abs_field_length);
        buffer[field_length] = 0;
        memmove(string, string + abs_field_length, strlen(string + abs_field_length) + 1);
      }
    } else if (SDDS_GetToken(string, buffer, bufferSize) < 0) {
      SDDS_SetError("Unable to scan data--tokenizing error (SDDS_ScanData)");
      return (0);
    }
  }
  switch (type) {
  case SDDS_SHORT:
    if (sscanf(buffer, "%hd", ((short *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_USHORT:
    if (sscanf(buffer, "%hu", ((unsigned short *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_LONG:
    if (sscanf(buffer, "%" SCNd32, ((int32_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_ULONG:
    if (sscanf(buffer, "%" SCNu32, ((uint32_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_LONG64:
    if (sscanf(buffer, "%" SCNd64, ((int64_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_ULONG64:
    if (sscanf(buffer, "%" SCNu64, ((uint64_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_FLOAT:
    if (sscanf(buffer, "%f", ((float *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_DOUBLE:
    if (sscanf(buffer, "%lf", ((double *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_LONGDOUBLE:
    if (sscanf(buffer, "%Lf", ((long double *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_STRING:
    if (is_parameter) {
      int32_t len;
      if (((char **)data)[index]) {
        free(((char **)data)[index]);
        ((char **)data)[index] = NULL;
      }
      if ((len = strlen(string)) > 0) {
        if (string[len - 1] == '\r')
          string[len - 1] = 0;
      }
      if (string[0] == '"')
        SDDS_GetToken(string, buffer, bufferSize);
      else
        strcpy(buffer, string);
      SDDS_InterpretEscapes(buffer);
      if (SDDS_CopyString(((char **)data) + index, buffer)) {
        if (buffer)
          free(buffer);
        return (1);
      }
    } else {
      if (field_length) {
        if (abs_field_length > (int32_t)strlen(string)) {
          strcpy(buffer, string);
          *string = 0;
        } else {
          strncpy(buffer, string, abs_field_length);
          buffer[abs_field_length] = 0;
          memmove(string, string + abs_field_length, strlen(string + abs_field_length) + 1);
        }
        if (field_length < 0)
          SDDS_RemovePadding(buffer);
      } else if (SDDS_GetToken(string, buffer, bufferSize) < 0)
        break;
      if (((char **)data)[index]) {
        free(((char **)data)[index]);
        ((char **)data)[index] = NULL;
      }
      SDDS_InterpretEscapes(buffer);
      if (SDDS_CopyString(((char **)data) + index, buffer)) {
        if (buffer)
          free(buffer);
        return (1);
      }
    }
    break;
  case SDDS_CHARACTER:
    SDDS_InterpretEscapes(buffer);
    *(((char *)data) + index) = buffer[0];
    if (buffer)
      free(buffer);
    return (1);
  default:
    SDDS_SetError("Unknown data type encountered (SDDS_ScanData)");
    return (0);
  }
  SDDS_SetError("Unable to scan data--scanning or allocation error (SDDS_ScanData)");
  return (0);
}

SDDS_ScanData2()

epicsShareFuncSDDS int32_t SDDS_ScanData2 ( char * string, char ** pstring, int32_t * strlength, int32_t type, int32_t field_length, void * data, int64_t index, int32_t is_parameter )

extern

Scans a string and saves the parsed value into a data pointer, optimized for long strings.

This function is similar to SDDS_ScanData but optimized for very long strings. It modifies the input string by advancing the string pointer and reducing its length after each call, which can improve performance when processing large amounts of data.

Parameters

string	Pointer to the input string containing the data to be scanned.
pstring	Pointer to the string pointer; this is updated to point to the next unread character.
strlength	Pointer to the length of the string; this is updated as the string is consumed.
type	The SDDS data type to interpret the scanned data as. Valid types include: SDDS_SHORT SDDS_USHORT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_FLOAT SDDS_DOUBLE SDDS_LONGDOUBLE SDDS_STRING SDDS_CHARACTER
field_length	Field length for fixed-field formats. Set to 0 for variable-field formats. If negative, indicates left-padding should be removed.
data	Void pointer to the data storage where the scanned value will be saved. Must be pre-allocated and appropriate for the specified data type.
index	The index within the data array where the value should be stored.
is_parameter	Set to 1 if the data is from an SDDS parameter; set to 0 for column data.

Returns

Returns 1 on success, or 0 on error. If an error occurs, an error message is set via SDDS_SetError().

Note

This function modifies the input string by advancing the pointer and reducing the length, which can lead to the original string being altered after each call. It is more efficient for processing very long strings compared to SDDS_ScanData.

Definition at line 1953 of file SDDS_ascii.c.

                                                                                                                                                              {
  char *buffer = NULL;
  int32_t abs_field_length, length;
  int32_t bufferSize = 0;
 
  abs_field_length = abs(field_length);
  if (!string) {
    SDDS_SetError("Unable to scan data--input string is NULL (SDDS_ScanData2)");
    return (0);
  }
  if (!data) {
    SDDS_SetError("Unable to scan data--data pointer is NULL (SDDS_ScanData2)");
    return (0);
  }
  if (!(buffer = SDDS_Malloc(sizeof(*buffer) * (bufferSize = SDDS_MAXLINE)))) {
    SDDS_SetError("Unable to scan data--allocation failure (SDDS_ScanData2)");
    return (0);
  }
  length = *strlength;
  if (length < abs_field_length)
    length = abs_field_length;
  if (bufferSize <= length) {
    if (!(buffer = SDDS_Realloc(buffer, sizeof(*buffer) * (bufferSize = 2 * length)))) {
      /* I allocate 2*length in the hopes that I won't need to realloc too often if I do this */
      SDDS_SetError("Unable to scan data--allocation failure (SDDS_ScanData2)");
      return (0);
    }
  }
  if (type != SDDS_STRING) {
    /* for non-string data, fill buffer with string to be scanned */
    if (field_length) {
      /* fill with fixed number of characters */
      if (abs_field_length > *strlength) {
        strcpy(buffer, string);
        **pstring = 0;
        *strlength = 0;
      } else {
        strncpy(buffer, string, abs_field_length);
        buffer[abs_field_length] = 0;
        *pstring += abs_field_length;
        *strlength -= abs_field_length;
      }
    } else if (SDDS_GetToken2(string, pstring, strlength, buffer, bufferSize) < 0) {
      SDDS_SetError("Unable to scan data--tokenizing error (SDDS_ScanData2)");
      return (0);
    }
  }
  switch (type) {
  case SDDS_SHORT:
    if (sscanf(buffer, "%hd", ((short *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_USHORT:
    if (sscanf(buffer, "%hu", ((unsigned short *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_LONG:
    if (sscanf(buffer, "%" SCNd32, ((int32_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_ULONG:
    if (sscanf(buffer, "%" SCNu32, ((uint32_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_LONG64:
    if (sscanf(buffer, "%" SCNd64, ((int64_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_ULONG64:
    if (sscanf(buffer, "%" SCNu64, ((uint64_t *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_FLOAT:
    if (sscanf(buffer, "%f", ((float *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_DOUBLE:
    if (sscanf(buffer, "%lf", ((double *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_LONGDOUBLE:
    if (sscanf(buffer, "%Lf", ((long double *)data) + index) == 1) {
      if (buffer)
        free(buffer);
      return (1);
    }
    break;
  case SDDS_STRING:
    if (is_parameter) {
      int32_t len;
      if (((char **)data)[index]) {
        free(((char **)data)[index]);
        ((char **)data)[index] = NULL;
      }
      if ((len = *strlength) > 0) {
        if (*pstring[len - 1] == '\r') {
          *pstring[len - 1] = 0;
          *strlength -= 1;
        }
      }
      if (*pstring[0] == '"')
        SDDS_GetToken2(*pstring, pstring, strlength, buffer, bufferSize);
      else
        strcpy(buffer, string);
      SDDS_InterpretEscapes(buffer);
      if (SDDS_CopyString(((char **)data) + index, buffer)) {
        if (buffer)
          free(buffer);
        return (1);
      }
    } else {
      if (field_length) {
        if (abs_field_length > *strlength) {
          strcpy(buffer, string);
          **pstring = 0;
          *strlength = 0;
        } else {
          strncpy(buffer, string, abs_field_length);
          buffer[abs_field_length] = 0;
          *pstring += abs_field_length;
          *strlength -= abs_field_length;
        }
        if (field_length < 0)
          SDDS_RemovePadding(buffer);
      } else if (SDDS_GetToken2(string, pstring, strlength, buffer, bufferSize) < 0)
        break;
      if (((char **)data)[index]) {
        free(((char **)data)[index]);
        ((char **)data)[index] = NULL;
      }
      SDDS_InterpretEscapes(buffer);
      if (SDDS_CopyString(((char **)data) + index, buffer)) {
        if (buffer)
          free(buffer);
        return (1);
      }
    }
    break;
  case SDDS_CHARACTER:
    SDDS_InterpretEscapes(buffer);
    *(((char *)data) + index) = buffer[0];
    if (buffer)
      free(buffer);
    return 1;
  default:
    SDDS_SetError("Unknown data type encountered (SDDS_ScanData2)");
    return (0);
  }
  SDDS_SetError("Unable to scan data--scanning or allocation error (SDDS_ScanData2)");
  return (0);
}

SDDS_SetArray()

epicsShareFuncSDDS int32_t SDDS_SetArray ( SDDS_DATASET * SDDS_dataset, char * array_name, int32_t mode, void * data_pointer, int32_t * dimension )

extern

Sets the values of an array variable in the SDDS dataset using specified dimensions.

This function assigns data to a specified array within the current SDDS dataset. The dimensions of the array are provided as an array of integers, allowing for the assignment of multi-dimensional arrays. The mode parameter controls how the data is interpreted and stored. This function handles both pointer arrays and contiguous data.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
array_name	The name of the array to set within the dataset.
mode	Bitwise flags that determine how the array is set. Valid flags include: SDDS_POINTER_ARRAY: Indicates that the array is a pointer array. SDDS_CONTIGUOUS_DATA: Indicates that the data is contiguous in memory.
data_pointer	Pointer to the data to be assigned to the array. The data must match the type defined for the array.
dimension	Pointer to an array of integers specifying the dimensions of the array. The number of dimensions should match the array definition.

Returns

Returns 1 on successful assignment of the array data. On failure, returns 0 and records an appropriate error message.

See also

SDDS_Realloc, SDDS_CopyStringArray, SDDS_SetError, SDDS_GetArrayIndex, SDDS_ZeroMemory, SDDS_AdvanceCounter

Definition at line 1284 of file SDDS_dataprep.c.

                                                                                                                          {
  int32_t index, i, size;
  int32_t *counter = NULL;
  SDDS_LAYOUT *layout;
  SDDS_ARRAY *array;
  void *ptr;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetArray"))
    return (0);
  if (!(mode & SDDS_POINTER_ARRAY) && !(mode & SDDS_CONTIGUOUS_DATA)) {
    SDDS_SetError("Unable to set array--invalid mode (SDDS_SetArray)");
    return (0);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to set array--unknown array name given (SDDS_SetArray)");
    return (0);
  }
 
  if (!dimension) {
    SDDS_SetError("Unable to set array--dimension pointer is NULL (SDDS_SetArray)");
    return (0);
  }
  if (!SDDS_dataset->array) {
    SDDS_SetError("Unable to set array--internal array pointer is NULL (SDDS_SetArray)");
    return (0);
  }
 
  layout = &SDDS_dataset->layout;
  array = SDDS_dataset->array + index;
  if (!layout->array_definition) {
    SDDS_SetError("Unable to set array--internal array definition pointer is NULL (SDDS_SetArray)");
    return (0);
  }
  array->definition = layout->array_definition + index;
  if (!array->dimension && !(array->dimension = (int32_t *)SDDS_Malloc(sizeof(*array->dimension) * array->definition->dimensions))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArray)");
    return (0);
  }
  array->elements = 1;
  for (i = 0; i < array->definition->dimensions; i++) {
    if ((array->dimension[i] = dimension[i]) < 0) {
      SDDS_SetError("Unable to set array--negative dimension specified (SDDS_SetArray)");
      return (0);
    }
    array->elements *= dimension[i];
    if (array->elements && !data_pointer) {
      SDDS_SetError("Unable to set array--data pointer is NULL (SDDS_SetArray)");
      return (0);
    }
  }
  if (!array->elements)
    return (1);
 
  size = SDDS_type_size[array->definition->type - 1];
  if (!(array->data = SDDS_Realloc(array->data, size * array->elements))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArray)");
    return (0);
  }
 
  /* handle 1-d arrays and contiguous data as a special case */
  if (array->definition->dimensions == 1 || mode & SDDS_CONTIGUOUS_DATA) {
    if (array->definition->type != SDDS_STRING)
      memcpy(array->data, data_pointer, size * array->elements);
    else if (!SDDS_CopyStringArray(array->data, data_pointer, array->elements)) {
      SDDS_SetError("Unable to set array--string copy failure (SDDS_SetArrayVararg");
      return (0);
    }
    return (1);
  }
 
  if (!(counter = SDDS_Realloc(counter, sizeof(*counter) * (array->elements - 1)))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArray)");
    return (0);
  }
  SDDS_ZeroMemory(counter, sizeof(*counter) * (array->elements - 1));
  index = 0;
  do {
    ptr = data_pointer;
    for (i = 0; i < array->definition->dimensions - 1; i++)
      ptr = ((void **)ptr)[counter[i]];
    if (array->definition->type != SDDS_STRING)
      memcpy((char *)array->data + size * index, ptr, size * array->dimension[i]);
    else if (!SDDS_CopyStringArray(((char **)array->data) + index, ptr, array->dimension[i])) {
      SDDS_SetError("Unable to set array--string copy failure (SDDS_SetArray)");
      return (0);
    }
    index += array->dimension[i];
  } while (SDDS_AdvanceCounter(counter, array->dimension, array->definition->dimensions - 1) != -1);
  if (counter)
    free(counter);
  return (1);
}

SDDS_SetArrayUnitsConversion()

epicsShareFuncSDDS int32_t SDDS_SetArrayUnitsConversion ( SDDS_DATASET * SDDS_dataset, char * array_name, char * new_units, char * old_units, double factor )

extern

Sets unit conversions for a specified array in an SDDS dataset.

This function updates the units of the specified array within the SDDS dataset and applies a conversion factor to all its elements if the dataset has already been read (i.e., pages_read > 0). The function ensures that the new units are consistent with the old units if provided.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
array_name	A null-terminated string specifying the name of the array to update.
new_units	A null-terminated string specifying the new units to assign to the array. This parameter must not be NULL.
old_units	A null-terminated string specifying the expected current units of the array. If NULL, the function does not verify the existing units.
factor	A double representing the conversion factor to apply to each element of the array. Each element will be multiplied by this factor.

Returns

Returns 1 on successful unit conversion and update. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that the unit conversion was successfully applied.
0	Indicates that an error occurred (e.g., invalid dataset, unrecognized array name, type undefined, memory allocation failure).

Note

• The new_units parameter must not be NULL. Passing NULL will result in an error.
• If the dataset has not been read yet (pages_read == 0), the conversion factor is stored but not applied immediately.
• The function handles various data types, ensuring that the conversion factor is appropriately applied based on the array's type.

See also

SDDS_SetColumnUnitsConversion, SDDS_SetParameterUnitsConversion, SDDS_GetArray

Definition at line 4676 of file SDDS_extract.c.

                                                                                                                                     {
  int32_t index, type;
  int64_t i;
  void *rawData;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetArrayUnitsConversion"))
    return(0);
  if (new_units == NULL) {
    SDDS_SetError("new_units is NULL (SDDS_SetArrayUnitsConversion)");
    return(0);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to get array--name is not recognized (SDDS_SetArrayUnitsConversion)");
    return(0);
  }
  if (!(type = SDDS_GetArrayType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get array--data type undefined (SDDS_SetArrayUnitsConversion)");
    return(0);
  }
  if (SDDS_dataset->layout.array_definition[index].units != NULL) {
    if (strcmp(new_units, SDDS_dataset->layout.array_definition[index].units) != 0) {
      if ((old_units != NULL) && (strcmp(old_units, SDDS_dataset->layout.array_definition[index].units) != 0)) {
        SDDS_SetError("Unexpected units value found (SDDS_SetArrayUnitsConversion)");
        return(0);
      }
      /* free(SDDS_dataset->layout.array_definition[index].units); */
      cp_str(&(SDDS_dataset->layout.array_definition[index].units), new_units);
    }
  } else {
    cp_str(&(SDDS_dataset->layout.array_definition[index].units), new_units);
  }
 
  if (SDDS_dataset->pages_read == 0) {
    return(1);
  }
  rawData = SDDS_dataset->array[index].data;
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((long double *)rawData)[i] *= factor;
    }
    break;
  case SDDS_DOUBLE:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((double *)rawData)[i] *= factor;
    }
    break;
  case SDDS_FLOAT:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((float *)rawData)[i] *= factor;
    }
    break;
  case SDDS_LONG:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((int32_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_ULONG:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((uint32_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_LONG64:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((int64_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_ULONG64:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((uint64_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_SHORT:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((short *)rawData)[i] *= factor;
    }
    break;
  case SDDS_USHORT:
    for (i = 0; i < SDDS_dataset->array[index].elements; i++) {
      ((unsigned short *)rawData)[i] *= factor;
    }
    break;
  }
  return(1);
}

SDDS_SetArrayVararg()

epicsShareFuncSDDS int32_t SDDS_SetArrayVararg ( SDDS_DATASET * SDDS_dataset, char * array_name, int32_t mode, void * data_pointer, ... )

extern

Sets the values of an array variable in the SDDS dataset using variable arguments for dimensions.

This function assigns data to a specified array within the current SDDS dataset. The dimensions of the array are provided as variable arguments, allowing for flexible assignment of multi-dimensional arrays. The mode parameter controls how the data is interpreted and stored. This function handles both pointer arrays and contiguous data.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
array_name	The name of the array to set within the dataset.
mode	Bitwise flags that determine how the array is set. Valid flags include: SDDS_POINTER_ARRAY: Indicates that the array is a pointer array. SDDS_CONTIGUOUS_DATA: Indicates that the data is contiguous in memory.
data_pointer	Pointer to the data to be assigned to the array. The data must match the type defined for the array.
...	Variable arguments specifying the dimensions of the array. The number of dimensions should match the array definition.

Returns

Returns 1 on successful assignment of the array data. On failure, returns 0 and records an appropriate error message.

See also

SDDS_Realloc, SDDS_CopyStringArray, SDDS_SetError, SDDS_GetArrayIndex, SDDS_ZeroMemory, SDDS_AdvanceCounter

Definition at line 1163 of file SDDS_dataprep.c.

                                                                                                                 {
  va_list argptr;
  int32_t index, retval, i, size;
  int32_t *counter = NULL;
  SDDS_LAYOUT *layout;
  SDDS_ARRAY *array;
  void *ptr;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetArrayVararg"))
    return (0);
  if (!(mode & SDDS_POINTER_ARRAY) && !(mode & SDDS_CONTIGUOUS_DATA)) {
    SDDS_SetError("Unable to set array--invalid mode (SDDS_SetArrayVararg)");
    return (0);
  }
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, array_name)) < 0) {
    SDDS_SetError("Unable to set array--unknown array name given (SDDS_SetArrayVararg)");
    return (0);
  }
  if (!SDDS_dataset->array) {
    SDDS_SetError("Unable to set array--internal array pointer is NULL (SDDS_SetArrayVararg)");
    return (0);
  }
 
  layout = &SDDS_dataset->layout;
  array = SDDS_dataset->array + index;
  if (!layout->array_definition) {
    SDDS_SetError("Unable to set array--internal array definition pointer is NULL (SDDS_SetArrayVararg)");
    return (0);
  }
  array->definition = layout->array_definition + index;
  if (!array->dimension && !(array->dimension = (int32_t *)SDDS_Malloc(sizeof(*array->dimension) * array->definition->dimensions))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArrayVararg)");
    return (0);
  }
 
  va_start(argptr, data_pointer);
 
  /* variable arguments are dimensions */
  retval = 1;
  index = 0;
  array->elements = 1;
  do {
    if ((array->dimension[index] = va_arg(argptr, int32_t)) < 0) {
      SDDS_SetError("Unable to set array--negative dimension given (SDDS_SetArrayVararg)");
      retval = 0;
      break;
    }
    array->elements *= array->dimension[index];
  } while (retval == 1 && ++index < array->definition->dimensions);
  va_end(argptr);
 
  if (!retval)
    return (0);
  if (!array->elements)
    return (1);
  if (!data_pointer) {
    SDDS_SetError("Unable to set array--data pointer is NULL (SDDS_SetArrayVararg)");
    return (0);
  }
 
  size = SDDS_type_size[array->definition->type - 1];
  if (!(array->data = SDDS_Realloc(array->data, size * array->elements))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArrayVararg");
    return (0);
  }
 
  /* handle 1-d arrays and contiguous data as a special case */
  if (array->definition->dimensions == 1 || mode & SDDS_CONTIGUOUS_DATA) {
    if (array->definition->type != SDDS_STRING)
      memcpy(array->data, data_pointer, size * array->elements);
    else if (!SDDS_CopyStringArray(array->data, data_pointer, array->elements)) {
      SDDS_SetError("Unable to set array--string copy failure (SDDS_SetArrayVararg");
      return (0);
    }
    return (1);
  }
 
  if (!(counter = SDDS_Realloc(counter, sizeof(*counter) * (array->elements - 1)))) {
    SDDS_SetError("Unable to set array--allocation failure (SDDS_SetArrayVararg");
    return (0);
  }
  SDDS_ZeroMemory(counter, sizeof(*counter) * (array->elements - 1));
  index = 0;
  do {
    ptr = data_pointer;
    for (i = 0; i < array->definition->dimensions - 1; i++)
      ptr = ((void **)ptr)[counter[i]];
    if (array->definition->type != SDDS_STRING)
      memcpy((char *)array->data + size * index, ptr, size * array->dimension[i]);
    else if (!SDDS_CopyStringArray(((char **)array->data) + index, ptr, array->dimension[i])) {
      SDDS_SetError("Unable to set array--string copy failure (SDDS_SetArrayVararg");
      return (0);
    }
    index += array->dimension[i];
  } while (SDDS_AdvanceCounter(counter, array->dimension, array->definition->dimensions - 1) != -1);
  if (counter)
    free(counter);
  return (1);
}

SDDS_SetAutoCheckMode()

epicsShareFuncSDDS uint32_t SDDS_SetAutoCheckMode

(

uint32_t

newMode

)

Sets the automatic check mode for SDDS dataset validation.

This function updates the auto-check mode, which controls the automatic validation of SDDS datasets during operations. The previous mode is returned.

Parameters

[in]

newMode

The new auto-check mode to be set. It should be a bitwise combination of the following constants: TABULAR_DATA_CHECKS: Enables checks for tabular data consistency. (Other mode flags as defined by SDDS)

Returns

The previous auto-check mode before the update.

See also

SDDS_CheckDataset

SDDS_CheckTabularData

Definition at line 597 of file SDDS_utils.c.

                                                 {
  uint32_t oldMode;
  mdb_thread_lock(&AutoCheckModeLock);
  oldMode = AutoCheckMode;
  AutoCheckMode = newMode;
  mdb_thread_unlock(&AutoCheckModeLock);
  return oldMode;
}

SDDS_SetAutoReadRecovery()

epicsShareFuncSDDS int32_t SDDS_SetAutoReadRecovery ( SDDS_DATASET * SDDS_dataset, uint32_t mode )

extern

Sets the auto-read recovery mode for the SDDS dataset.

Parameters

SDDS_dataset	The SDDS dataset to modify.
mode	The mode to set (SDDS_AUTOREADRECOVER or SDDS_NOAUTOREADRECOVER).

Returns

1 on success, 0 on error.

Definition at line 1787 of file SDDS_input.c.

                                                                            {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetAutoReadRecovery"))
    return 0;
  if (mode & SDDS_AUTOREADRECOVER) {
    SDDS_dataset->autoRecover = 1;
  } else if (mode & SDDS_NOAUTOREADRECOVER) {
    SDDS_dataset->autoRecover = 0;
  } else {
    SDDS_SetError("Invalid Auto Read Recovery mode (SDDS_SetAutoReadRecovery).");
    return 0;
  }
  return 1;
}

SDDS_SetColumn()

epicsShareFuncSDDS int32_t SDDS_SetColumn ( SDDS_DATASET * SDDS_dataset, int32_t mode, void * data, int64_t rows, ... )

extern

Sets the values for one data column in the current data table of an SDDS dataset.

This function assigns data to a specified column within the current data table of the given SDDS dataset. The column can be identified either by its index or by its name. The mode parameter determines how the column is identified. The function ensures that the number of rows in the new column matches the existing data table.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Bitwise flags that determine how the column is identified. Valid flags include: SDDS_SET_BY_INDEX: Identify the column by its index. SDDS_SET_BY_NAME: Identify the column by its name.
data	Pointer to an array of data to be assigned to the column. The elements of the array must be of the same type as the column type.
rows	The number of rows in the column. This should match the number of rows in the existing data table.
...	Variable arguments specifying either the column index or column name, depending on the mode parameter: If mode includes SDDS_SET_BY_INDEX: Provide an int32_t index. If mode includes SDDS_SET_BY_NAME: Provide a char* name.

Returns

Returns 1 on successful assignment of the column data. On failure, returns 0 and records an appropriate error message.

Note

The function ensures that the number of rows in the new column matches the existing data table. If the data type of the column is SDDS_STRING, it handles memory allocation and copying of strings appropriately.

See also

SDDS_SetRowValues, SDDS_SetError, SDDS_GetColumnIndex, SDDS_CopyStringArray

Definition at line 1542 of file SDDS_dataprep.c.

                                                                                                {
  va_list argptr;
  int32_t index;
  int32_t retval;
  SDDS_LAYOUT *layout;
  char *name;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumn"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME)) {
    SDDS_SetError("Unable to set column values--unknown mode (SDDS_SetColumn)");
    return (0);
  }
  if (rows > SDDS_dataset->n_rows_allocated) {
    SDDS_SetError("Unable to set column values--number of rows exceeds allocated memory (SDDS_SetColumn)");
    return (0);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_SetColumn"))
    return (0);
  if (SDDS_dataset->n_rows != 0 && SDDS_dataset->n_rows != rows) {
    SDDS_SetError("Number of rows in new column unequal to number in other columns (SDDS_SetColumn)");
    return (0);
  }
  SDDS_dataset->n_rows = rows;
  layout = &SDDS_dataset->layout;
 
  retval = 1;
  va_start(argptr, rows);
  if (mode & SDDS_SET_BY_INDEX) {
    index = va_arg(argptr, int32_t);
    if (index < 0 || index >= layout->n_columns) {
      SDDS_SetError("Unable to set column values--index out of range (SDDS_SetColumn)");
      retval = 0;
    }
  } else {
    name = va_arg(argptr, char *);
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0) {
      SDDS_SetError0("Unable to set column values--name ");
      SDDS_SetError0(name);
      SDDS_SetError(" not recognized (SDDS_SetColumn)");
      retval = 0;
    }
  }
  va_end(argptr);
  if (!retval)
    return 0;
 
  if (layout->column_definition[index].type == SDDS_STRING) {
    if (SDDS_dataset->data[index]) {
      char *ptr;
      int64_t i;
      for (i = 0; i < rows; i++) {
        ptr = *((char **)SDDS_dataset->data[index] + i);
        if (ptr)
          free(ptr);
        *((char **)SDDS_dataset->data[index] + i) = NULL;
      }
    }
    if (!SDDS_CopyStringArray((char **)(SDDS_dataset->data[index]), (char **)data, rows)) {
      SDDS_SetError("Unable to set column--error copying string data (SDDS_SetColumn)");
      return 0;
    }
  } else
    memcpy(SDDS_dataset->data[index], data, rows * SDDS_type_size[layout->column_definition[index].type - 1]);
  return 1;
}

SDDS_SetColumnFlags()

epicsShareFuncSDDS int32_t SDDS_SetColumnFlags ( SDDS_DATASET * SDDS_dataset, int32_t column_flag_value )

extern

Sets the acceptance flags for all columns in the current data table of a data set.

This function initializes the acceptance flags for each column. A non-zero flag indicates that the column is "of interest" and should be considered in subsequent operations, while a zero flag marks the column for rejection.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
column_flag_value	Integer value to assign to all column flags. Non-zero value: Marks columns as accepted ("of interest"). Zero value: Marks columns as rejected.

Returns

• 1 on successful update of column flags.
• 0 on failure, with an error message recorded (e.g., memory allocation failure).

Note

This function overwrites any existing column flags with the specified column_flag_value. It also updates the column_order array accordingly.

See also

SDDS_GetColumnFlags, SDDS_AssertColumnFlags

Definition at line 218 of file SDDS_extract.c.

                                                                                   {
  int64_t i;
  /*  int32_t j; */
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumnFlags"))
    return 0;
  if ((!SDDS_dataset->column_flag || !SDDS_dataset->column_order) && !SDDS_AllocateColumnFlags(SDDS_dataset))
    return 0;
  if (!SDDS_SetMemory(SDDS_dataset->column_flag, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)column_flag_value, (int32_t)0)) {
    SDDS_SetError("Unable to set column flags--memory filling failed (SDDS_SetColumnFlags)");
    return (0);
  }
  SDDS_dataset->n_of_interest = column_flag_value ? SDDS_dataset->layout.n_columns : 0;
  for (i = 0; i < SDDS_dataset->layout.n_columns; i++)
    SDDS_dataset->column_order[i] = column_flag_value ? i : -1;
  return (1);
}

SDDS_SetColumnFromDoubles()

epicsShareFuncSDDS int32_t SDDS_SetColumnFromDoubles ( SDDS_DATASET * SDDS_dataset, int32_t mode, double * data, int64_t rows, ... )

extern

Sets the values for a single data column using double-precision floating-point numbers.

This function assigns data to a specified column within the current data table of the given SDDS dataset. The column can be identified either by its index or by its name, based on the provided mode. The data provided must be in the form of double-precision floating-point numbers (double). If the target column is of a different numeric type, the function will perform the necessary type casting. For string columns, the function converts the double values to strings with appropriate formatting.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Bitwise flags that determine how the column is identified. Valid flags include: SDDS_SET_BY_INDEX: Identify the column by its index. SDDS_SET_BY_NAME: Identify the column by its name.

Mode Requirements:

• Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set.

Syntax Based on Mode Combination:

• SDDS_SET_BY_INDEX: int32_t SDDS_SetColumnFromDoubles(SDDS_DATASET *SDDS_dataset, int32_t mode, double *data, int64_t rows, int32_t index)
• SDDS_SET_BY_NAME: int32_t SDDS_SetColumnFromDoubles(SDDS_DATASET *SDDS_dataset, int32_t mode, double *data, int64_t rows, char *name)

Parameters

data	Pointer to an array of double-precision floating-point data to be assigned to the column. The array should contain at least rows elements.
rows	The number of rows (elements) in the column to be set. Must not exceed the allocated memory for the dataset.
...	Variable arguments specifying either the column index (int32_t) or column name (char *), depending on the mode.

Returns

Returns 1 on successful assignment of the column data. On failure, returns 0 and records an appropriate error message using SDDS_SetError.

Note

• If the target column is of type SDDS_STRING, the function converts each double value to a string with a precision of up to 15 significant digits.
• The function ensures that the number of rows in the new column matches the existing data table.
• It is required to call SDDS_StartPage before setting column values.

See also

SDDS_SetColumnFromLongDoubles, SDDS_SetError, SDDS_GetColumnIndex, SDDS_CopyStringArray, SDDS_CastValue

Definition at line 1648 of file SDDS_dataprep.c.

                                                                                                             {
  va_list argptr;
  int64_t i;
  int32_t index, retval, type, size;
  SDDS_LAYOUT *layout;
  char *name;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumnFromDoubles"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME)) {
    SDDS_SetError("Unable to set column values--unknown mode (SDDS_SetColumnFromDoubles)");
    return (0);
  }
  if (rows > SDDS_dataset->n_rows_allocated) {
    SDDS_SetError("Unable to set column values--number of rows exceeds allocated memory (SDDS_SetColumnFromDoubles)");
    return (0);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_SetColumnFromDoubles"))
    return (0);
  if (SDDS_dataset->n_rows != 0 && SDDS_dataset->n_rows != rows) {
    SDDS_SetError("Number of rows in new column unequal to number in other columns (SDDS_SetColumnFromDoubles)");
    return (0);
  }
  SDDS_dataset->n_rows = rows;
  layout = &SDDS_dataset->layout;
 
  retval = 1;
  va_start(argptr, rows);
  if (mode & SDDS_SET_BY_INDEX) {
    index = va_arg(argptr, int32_t);
    if (index < 0 || index >= layout->n_columns) {
      SDDS_SetError("Unable to set column values--index out of range (SDDS_SetColumnFromDoubles)");
      retval = 0;
    }
  } else {
    name = va_arg(argptr, char *);
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0) {
      SDDS_SetError("Unable to set column values--name not recognized (SDDS_SetColumnFromDoubles)");
      retval = 0;
    }
  }
  va_end(argptr);
  if (!retval)
    return 0;
 
  type = layout->column_definition[index].type;
  if (!SDDS_NUMERIC_TYPE(type)) {
    if (type == SDDS_STRING) {
      char **stringArray;
      if (SDDS_dataset->data[index]) {
        char *ptr;
        int64_t i;
        for (i = 0; i < rows; i++) {
          ptr = *((char **)SDDS_dataset->data[index] + i);
          if (ptr)
            free(ptr);
          *((char **)SDDS_dataset->data[index] + i) = NULL;
        }
      }
      stringArray = (char **)malloc(sizeof(char *) * rows);
      for (i = 0; i < rows; i++) {
        stringArray[i] = (char *)malloc(sizeof(char) * 40);
        sprintf(stringArray[i], "%.15lg", data[i]);
      }
      if (!SDDS_CopyStringArray((char **)(SDDS_dataset->data[index]), (char **)stringArray, rows)) {
        SDDS_SetError("Unable to set column--error copying string data (SDDS_SetColumnFromDoubles)");
        return 0;
      }
      for (i = 0; i < rows; i++) {
        free(stringArray[i]);
      }
      free(stringArray);
      return 1;
    }
    SDDS_SetError("Unable to set column--source type is nonnumeric (SDDS_SetColumnFromDoubles)");
    return 0;
  }
 
  size = SDDS_type_size[layout->column_definition[index].type - 1];
 
  if (type == SDDS_DOUBLE) {
    memcpy((char *)SDDS_dataset->data[index], (char *)data, rows * size);
    return 1;
  }
 
  for (i = 0; i < rows; i++)
    if (!SDDS_CastValue(data, i, SDDS_DOUBLE, type, (char *)(SDDS_dataset->data[index]) + i * size)) {
      SDDS_SetError("Unable to set column--cast error (SDDS_SetColumnFromDoubles)");
      return 0;
    }
 
  return 1;
}

SDDS_SetColumnFromFloats()

epicsShareFuncSDDS int32_t SDDS_SetColumnFromFloats ( SDDS_DATASET * SDDS_dataset, int32_t mode, float * data, int64_t rows, ... )

extern

Sets the values for a single data column using single-precision floating-point numbers.

This function assigns data to a specified column within the current data table of the given SDDS dataset. The column can be identified either by its index or by its name, based on the provided mode. The data provided must be in the form of single-precision floating-point numbers (float). If the target column is of a different numeric type, the function will perform the necessary type casting. For string columns, the function converts the float values to strings with appropriate formatting.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Bitwise flags that determine how the column is identified. Valid flags include: SDDS_SET_BY_INDEX: Identify the column by its index. SDDS_SET_BY_NAME: Identify the column by its name.

Mode Requirements:

• Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set.

Syntax Based on Mode Combination:

• SDDS_SET_BY_INDEX: int32_t SDDS_SetColumnFromFloats(SDDS_DATASET *SDDS_dataset, int32_t mode, float *data, int64_t rows, int32_t index)
• SDDS_SET_BY_NAME: int32_t SDDS_SetColumnFromFloats(SDDS_DATASET *SDDS_dataset, int32_t mode, float *data, int64_t rows, char *name)

Parameters

data	Pointer to an array of single-precision floating-point data to be assigned to the column. The array should contain at least rows elements.
rows	The number of rows (elements) in the column to be set. Must not exceed the allocated memory for the dataset.
...	Variable arguments specifying either the column index (int32_t) or column name (char *), depending on the mode.

Returns

Returns 1 on successful assignment of the column data. On failure, returns 0 and records an appropriate error message using SDDS_SetError.

Note

• If the target column is of type SDDS_STRING, the function converts each float value to a string with a precision of up to 8 significant digits.
• The function ensures that the number of rows in the new column matches the existing data table.
• It is required to call SDDS_StartPage before setting column values.

See also

SDDS_SetColumnFromDoubles, SDDS_SetError, SDDS_GetColumnIndex, SDDS_CopyStringArray, SDDS_CastValue

Definition at line 1918 of file SDDS_dataprep.c.

                                                                                                           {
  va_list argptr;
  int64_t i;
  int32_t index, retval, type, size;
  SDDS_LAYOUT *layout;
  char *name;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumnFromFloats"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME)) {
    SDDS_SetError("Unable to set column values--unknown mode (SDDS_SetColumnFromFloats)");
    return (0);
  }
  if (rows > SDDS_dataset->n_rows_allocated) {
    SDDS_SetError("Unable to set column values--number of rows exceeds allocated memory (SDDS_SetColumnFromFloats)");
    return (0);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_SetColumnFromFloats"))
    return (0);
  if (SDDS_dataset->n_rows != 0 && SDDS_dataset->n_rows != rows) {
    SDDS_SetError("Number of rows in new column unequal to number in other columns (SDDS_SetColumnFromFloats)");
    return (0);
  }
  SDDS_dataset->n_rows = rows;
  layout = &SDDS_dataset->layout;
 
  retval = 1;
  va_start(argptr, rows);
  if (mode & SDDS_SET_BY_INDEX) {
    index = va_arg(argptr, int32_t);
    if (index < 0 || index >= layout->n_columns) {
      SDDS_SetError("Unable to set column values--index out of range (SDDS_SetColumnFromFloats)");
      retval = 0;
    }
  } else {
    name = va_arg(argptr, char *);
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0) {
      SDDS_SetError("Unable to set column values--name not recognized (SDDS_SetColumnFromFloats)");
      retval = 0;
    }
  }
  va_end(argptr);
  if (!retval)
    return 0;
 
  type = layout->column_definition[index].type;
  if (!SDDS_NUMERIC_TYPE(type)) {
    if (type == SDDS_STRING) {
      char **stringArray;
      if (SDDS_dataset->data[index]) {
        char *ptr;
        int64_t i;
        for (i = 0; i < rows; i++) {
          ptr = *((char **)SDDS_dataset->data[index] + i);
          if (ptr)
            free(ptr);
          *((char **)SDDS_dataset->data[index] + i) = NULL;
        }
      }
      stringArray = (char **)malloc(sizeof(char *) * rows);
      for (i = 0; i < rows; i++) {
        stringArray[i] = (char *)malloc(sizeof(char) * 40);
        sprintf(stringArray[i], "%.8g", data[i]);
      }
      if (!SDDS_CopyStringArray((char **)(SDDS_dataset->data[index]), (char **)stringArray, rows)) {
        SDDS_SetError("Unable to set column--error copying string data (SDDS_SetColumnFromFloats)");
        return 0;
      }
      for (i = 0; i < rows; i++) {
        free(stringArray[i]);
      }
      free(stringArray);
      return 1;
    }
    SDDS_SetError("Unable to set column--source type is nonnumeric (SDDS_SetColumnFromFloats)");
    return 0;
  }
 
  size = SDDS_type_size[layout->column_definition[index].type - 1];
 
  if (type == SDDS_FLOAT) {
    memcpy((char *)SDDS_dataset->data[index], (char *)data, rows * size);
    return 1;
  }
 
  for (i = 0; i < rows; i++)
    if (!SDDS_CastValue(data, i, SDDS_FLOAT, type, (char *)(SDDS_dataset->data[index]) + i * size)) {
      SDDS_SetError("Unable to set column--cast error (SDDS_SetColumnFromFloats)");
      return 0;
    }
 
  return 1;
}

SDDS_SetColumnFromLongs()

epicsShareFuncSDDS int32_t SDDS_SetColumnFromLongs ( SDDS_DATASET * SDDS_dataset, int32_t mode, int32_t * data, int64_t rows, ... )

extern

Sets the values for a single data column using long integer numbers.

This function assigns data to a specified column within the current data table of the given SDDS dataset. The column can be identified either by its index or by its name, based on the provided mode. The data provided must be in the form of long integers (int32_t). If the target column is of a different numeric type, the function will perform the necessary type casting. For string columns, the function converts the integer values to strings with appropriate formatting.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Bitwise flags that determine how the column is identified. Valid flags include: SDDS_SET_BY_INDEX: Identify the column by its index. SDDS_SET_BY_NAME: Identify the column by its name.

Mode Requirements:

• Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set.

Syntax Based on Mode Combination:

• SDDS_SET_BY_INDEX: int32_t SDDS_SetColumnFromLongs(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t *data, int64_t rows, int32_t index)
• SDDS_SET_BY_NAME: int32_t SDDS_SetColumnFromLongs(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t *data, int64_t rows, char *name)

Parameters

data	Pointer to an array of long integer data to be assigned to the column. The array should contain at least rows elements.
rows	The number of rows (elements) in the column to be set. Must not exceed the allocated memory for the dataset.
...	Variable arguments specifying either the column index (int32_t) or column name (char *), depending on the mode.

Returns

Returns 1 on successful assignment of the column data. On failure, returns 0 and records an appropriate error message using SDDS_SetError.

Note

• If the target column is of type SDDS_STRING, the function converts each long integer value to a string using the sprintf function with the appropriate format specifier.
• The function ensures that the number of rows in the new column matches the existing data table.
• It is required to call SDDS_StartPage before setting column values.

See also

SDDS_SetColumnFromDoubles, SDDS_SetError, SDDS_GetColumnIndex, SDDS_CopyStringArray, SDDS_CastValue

Definition at line 2051 of file SDDS_dataprep.c.

                                                                                                            {
  va_list argptr;
  int64_t i;
  int32_t index, retval, type, size;
  SDDS_LAYOUT *layout;
  char *name;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumnFromLongs"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME)) {
    SDDS_SetError("Unable to set column values--unknown mode (SDDS_SetColumnFromLongs)");
    return (0);
  }
  if (rows > SDDS_dataset->n_rows_allocated) {
    SDDS_SetError("Unable to set column values--number of rows exceeds allocated memory (SDDS_SetColumnFromLongs)");
    return (0);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_SetColumnFromLongs"))
    return (0);
  if (SDDS_dataset->n_rows != 0 && SDDS_dataset->n_rows != rows) {
    SDDS_SetError("Number of rows in new column unequal to number in other columns (SDDS_SetColumnFromLongs)");
    return (0);
  }
  SDDS_dataset->n_rows = rows;
  layout = &SDDS_dataset->layout;
 
  retval = 1;
  va_start(argptr, rows);
  if (mode & SDDS_SET_BY_INDEX) {
    index = va_arg(argptr, int32_t);
    if (index < 0 || index >= layout->n_columns) {
      SDDS_SetError("Unable to set column values--index out of range (SDDS_SetColumnFromLongs)");
      retval = 0;
    }
  } else {
    name = va_arg(argptr, char *);
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0) {
      SDDS_SetError("Unable to set column values--name not recognized (SDDS_SetColumnFromLongs)");
      retval = 0;
    }
  }
  va_end(argptr);
  if (!retval)
    return 0;
 
  type = layout->column_definition[index].type;
  if (!SDDS_NUMERIC_TYPE(type)) {
    if (type == SDDS_STRING) {
      char **stringArray;
      if (SDDS_dataset->data[index]) {
        char *ptr;
        int64_t i;
        for (i = 0; i < rows; i++) {
          ptr = *((char **)SDDS_dataset->data[index] + i);
          if (ptr)
            free(ptr);
          *((char **)SDDS_dataset->data[index] + i) = NULL;
        }
      }
      stringArray = (char **)malloc(sizeof(char *) * rows);
      for (i = 0; i < rows; i++) {
        stringArray[i] = (char *)malloc(sizeof(char) * 40);
        sprintf(stringArray[i], "%" PRId32, data[i]);
      }
      if (!SDDS_CopyStringArray((char **)(SDDS_dataset->data[index]), (char **)stringArray, rows)) {
        SDDS_SetError("Unable to set column--error copying string data (SDDS_SetColumnFromLongs)");
        return 0;
      }
      for (i = 0; i < rows; i++) {
        free(stringArray[i]);
      }
      free(stringArray);
      return 1;
    }
    SDDS_SetError("Unable to set column--source type is nonnumeric (SDDS_SetColumnFromLongs)");
    return 0;
  }
 
  size = SDDS_type_size[layout->column_definition[index].type - 1];
 
  if (type == SDDS_LONG) {
    memcpy((char *)SDDS_dataset->data[index], (char *)data, rows * size);
    return 1;
  }
 
  for (i = 0; i < rows; i++)
    if (!SDDS_CastValue(data, i, SDDS_LONG, type, (char *)(SDDS_dataset->data[index]) + i * size)) {
      SDDS_SetError("Unable to set column--cast error (SDDS_SetColumnFromLongs)");
      return 0;
    }
 
  return 1;
}

SDDS_SetColumnMemoryMode()

epicsShareFuncSDDS void SDDS_SetColumnMemoryMode ( SDDS_DATASET * SDDS_dataset, uint32_t mode )

extern

Sets the column memory mode for the SDDS dataset.

Parameters

SDDS_dataset	The SDDS dataset to operate on.
mode	The column memory mode to set.

Definition at line 1371 of file SDDS_input.c.

                                                                         {
  SDDS_dataset->layout.data_mode.column_memory_mode = mode;
}

SDDS_SetColumnsOfInterest()

epicsShareFuncSDDS int32_t SDDS_SetColumnsOfInterest ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Sets the acceptance flags for columns based on specified naming criteria.

This function allows modifying column acceptance flags using various methods, including specifying column names directly or using pattern matching.

Supported modes:

• SDDS_NAME_ARRAY: Provide an array of column names to mark as "of interest".
• SDDS_NAMES_STRING: Provide a single string containing comma-separated column names.
• SDDS_NAME_STRINGS: Provide multiple individual column name strings, terminated by NULL.
• SDDS_MATCH_STRING: Provide a pattern string and a logic mode to match column names.

A non-zero flag indicates that a column is "of interest", while a zero flag marks it for rejection.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	Operation mode determining how columns are selected. Possible values: SDDS_NAME_ARRAY: c SDDS_SetColumnsOfInterest(SDDS_DATASET *SDDS_dataset, SDDS_NAME_ARRAY, int32_t n_entries, char **nameArray); SDDS_NAMES_STRING: c SDDS_SetColumnsOfInterest(SDDS_DATASET *SDDS_dataset, SDDS_NAMES_STRING, char *names); SDDS_NAME_STRINGS: c SDDS_SetColumnsOfInterest(SDDS_DATASET *SDDS_dataset, SDDS_NAME_STRINGS, char *name1, char *name2, ..., NULL); SDDS_MATCH_STRING: c SDDS_SetColumnsOfInterest(SDDS_DATASET *SDDS_dataset, SDDS_MATCH_STRING, char *pattern, int32_t logic_mode);
...	Variable arguments based on the selected mode: SDDS_NAME_ARRAY: int32_t n_entries: Number of column names in the array. char **nameArray: Array of column name strings. SDDS_NAMES_STRING: char *names: Comma-separated string of column names. SDDS_NAME_STRINGS: char *name1, char *name2, ..., NULL: Individual column name strings terminated by NULL. SDDS_MATCH_STRING: char *pattern: Pattern string to match column names (supports wildcards). int32_t logic_mode: Logic mode for matching (e.g., AND, OR).

Returns

• 1 on successful update of column flags.
• 0 on failure, with an error message recorded (e.g., invalid mode, memory issues, unrecognized column names).

Note

• When using SDDS_MATCH_STRING, the pattern may include wildcards to match multiple column names.
• Ensure that column names provided exist within the dataset to avoid errors.

See also

SDDS_SetColumnFlags, SDDS_AssertColumnFlags, SDDS_GetColumnFlags

Definition at line 432 of file SDDS_extract.c.

{
  va_list argptr;
  int32_t i, j, index, n_names;
  int32_t retval;
  /*  int32_t type; */
  char **name, *string, *match_string, *ptr;
  int32_t local_memory; /* (0,1,2) --> (none, pointer array, pointer array + strings) locally allocated */
  char buffer[SDDS_MAXLINE];
  int32_t logic;
 
  name = NULL;
  n_names = local_memory = logic = 0;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumnsOfInterest"))
    return (0);
  if ((!SDDS_dataset->column_flag || !SDDS_dataset->column_order) && !SDDS_AllocateColumnFlags(SDDS_dataset))
    return 0;
  va_start(argptr, mode);
  retval = -1;
  match_string = NULL;
  switch (mode) {
  case SDDS_NAME_ARRAY:
    local_memory = 0;
    n_names = va_arg(argptr, int32_t);
    name = va_arg(argptr, char **);
    break;
  case SDDS_NAMES_STRING:
    local_memory = 2;
    n_names = 0;
    name = NULL;
    ptr = va_arg(argptr, char *);
    SDDS_CopyString(&string, ptr);
    while ((ptr = strchr(string, ',')))
      *ptr = ' ';
    while (SDDS_GetToken(string, buffer, SDDS_MAXLINE) > 0) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1))) || !SDDS_CopyString(name + n_names, buffer)) {
        SDDS_SetError("Unable to process column selection--memory allocation failure (SDDS_SetColumnsOfInterest)");
        retval = 0;
        break;
      }
      n_names++;
    }
    free(string);
    break;
  case SDDS_NAME_STRINGS:
    local_memory = 1;
    n_names = 0;
    name = NULL;
    while ((string = va_arg(argptr, char *))) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1)))) {
        SDDS_SetError("Unable to process column selection--memory allocation failure (SDDS_SetColumnsOfInterest)");
        retval = 0;
        break;
      }
      name[n_names++] = string;
    }
    break;
  case SDDS_MATCH_STRING:
    local_memory = 0;
    n_names = 1;
    if (!(string = va_arg(argptr, char *))) {
      SDDS_SetError("Unable to process column selection--invalid matching string (SDDS_SetColumnsOfInterest)");
      retval = 0;
      break;
    }
    match_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    break;
  default:
    SDDS_SetError("Unable to process column selection--unknown mode (SDDS_SetColumnsOfInterest)");
    retval = 0;
    break;
  }
 
  va_end(argptr);
  if (retval != -1)
    return (retval);
 
  if (n_names == 0) {
    SDDS_SetError("Unable to process column selection--no names in call (SDDS_SetColumnsOfInterest)");
    return (0);
  }
  if (!SDDS_dataset->column_order) {
    SDDS_SetError("Unable to process column selection--'column_order' array in SDDS_DATASET is NULL (SDDS_SetColumnsOfInterest)");
    return (0);
  }
 
  if (mode != SDDS_MATCH_STRING) {
    for (i = 0; i < n_names; i++) {
      if ((index = SDDS_GetColumnIndex(SDDS_dataset, name[i])) < 0) {
        sprintf(buffer, "Unable to process column selection--unrecognized column name %s seen (SDDS_SetColumnsOfInterest)", name[i]);
        SDDS_SetError(buffer);
        return (0);
      }
      for (j = 0; j < SDDS_dataset->n_of_interest; j++)
        if (index == SDDS_dataset->column_order[j])
          break;
      if (j == SDDS_dataset->n_of_interest) {
        SDDS_dataset->column_flag[index] = 1;
        SDDS_dataset->column_order[j] = index;
        SDDS_dataset->n_of_interest++;
      }
    }
  } else {
    for (i = 0; i < SDDS_dataset->layout.n_columns; i++) {
      if (SDDS_Logic(SDDS_dataset->column_flag[i], wild_match(SDDS_dataset->layout.column_definition[i].name, match_string), logic)) {
#if defined(DEBUG)
        fprintf(stderr, "logic match of %s to %s\n", SDDS_dataset->layout.column_definition[i].name, match_string);
#endif
        for (j = 0; j < SDDS_dataset->n_of_interest; j++)
          if (i == SDDS_dataset->column_order[j])
            break;
        if (j == SDDS_dataset->n_of_interest) {
          SDDS_dataset->column_flag[i] = 1;
          SDDS_dataset->column_order[j] = i;
          SDDS_dataset->n_of_interest++;
        }
      } else {
#if defined(DEBUG)
        fprintf(stderr, "no logic match of %s to %s\n", SDDS_dataset->layout.column_definition[i].name, match_string);
#endif
        SDDS_dataset->column_flag[i] = 0;
        for (j = 0; j < SDDS_dataset->n_of_interest; j++)
          if (i == SDDS_dataset->column_order[j])
            break;
        if (j != SDDS_dataset->n_of_interest) {
          for (j++; j < SDDS_dataset->n_of_interest; j++)
            SDDS_dataset->column_order[j - 1] = SDDS_dataset->column_order[j];
        }
      }
    }
    free(match_string);
  }
 
#if defined(DEBUG)
  for (i = 0; i < SDDS_dataset->n_of_interest; i++)
    fprintf(stderr, "column %" PRId32 " will be %s\n", i, SDDS_dataset->layout.column_definition[SDDS_dataset->column_order[i]].name);
#endif
 
  if (local_memory == 2) {
    for (i = 0; i < n_names; i++)
      free(name[i]);
  }
  if (local_memory >= 1)
    free(name);
 
  return (1);
}

SDDS_SetColumnUnitsConversion()

epicsShareFuncSDDS int32_t SDDS_SetColumnUnitsConversion ( SDDS_DATASET * SDDS_dataset, char * column_name, char * new_units, char * old_units, double factor )

extern

Sets unit conversions for a specified column in an SDDS dataset.

This function updates the units of the specified column within the SDDS dataset and applies a conversion factor to all its elements if the dataset has already been read (i.e., pages_read > 0). The function ensures that the new units are consistent with the old units if provided.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
column_name	A null-terminated string specifying the name of the column to update.
new_units	A null-terminated string specifying the new units to assign to the column. This parameter must not be NULL.
old_units	A null-terminated string specifying the expected current units of the column. If NULL, the function does not verify the existing units.
factor	A double representing the conversion factor to apply to each element of the column. Each element will be multiplied by this factor.

Returns

Returns 1 on successful unit conversion and update. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that the unit conversion was successfully applied.
0	Indicates that an error occurred (e.g., invalid dataset, unrecognized column name, type undefined, memory allocation failure).

Note

• The new_units parameter must not be NULL. Passing NULL will result in an error.
• If the dataset has not been read yet (pages_read == 0), the conversion factor is stored but not applied immediately.
• The function handles various data types, ensuring that the conversion factor is appropriately applied based on the column's type.

See also

SDDS_SetArrayUnitsConversion, SDDS_SetParameterUnitsConversion, SDDS_GetColumn

Definition at line 4789 of file SDDS_extract.c.

                                                                                                                                       {
  int32_t index, type;
  int64_t i;
  void *rawData;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetColumnUnitsConversion"))
    return(0);
  if (new_units == NULL) {
    SDDS_SetError("new_units is NULL (SDDS_SetColumnUnitsConversion)");
    return(0);
  }
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, column_name)) < 0) {
    SDDS_SetError("Unable to get column--name is not recognized (SDDS_SetColumnUnitsConversion)");
    return(0);
  }
  if (!(type = SDDS_GetColumnType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get column--data type undefined (SDDS_SetColumnUnitsConversion)");
    return(0);
  }
  if (SDDS_dataset->layout.column_definition[index].units != NULL) {
    if (strcmp(new_units, SDDS_dataset->layout.column_definition[index].units) != 0) {
      if ((old_units != NULL) && (strcmp(old_units, SDDS_dataset->layout.column_definition[index].units) != 0)) {
        SDDS_SetError("Unexpected units value found (SDDS_SetColumnUnitsConversion)");
        return(0);
      }
      free(SDDS_dataset->layout.column_definition[index].units);
      cp_str(&(SDDS_dataset->original_layout.column_definition[index].units), new_units);
      cp_str(&(SDDS_dataset->layout.column_definition[index].units), new_units);
    }
  } else {
    cp_str(&(SDDS_dataset->original_layout.column_definition[index].units), new_units);
    cp_str(&(SDDS_dataset->layout.column_definition[index].units), new_units);
  }
 
  if (SDDS_dataset->pages_read == 0) {
    return(1);
  }
  rawData = SDDS_dataset->data[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((long double *)rawData)[i] *= factor;
    }
    break;
  case SDDS_DOUBLE:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((double *)rawData)[i] *= factor;
    }
    break;
  case SDDS_FLOAT:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((float *)rawData)[i] *= factor;
    }
    break;
  case SDDS_LONG:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((int32_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_ULONG:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((uint32_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_LONG64:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((int64_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_ULONG64:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((uint64_t *)rawData)[i] *= factor;
    }
    break;
  case SDDS_SHORT:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((short *)rawData)[i] *= factor;
    }
    break;
  case SDDS_USHORT:
    for (i = 0; i < SDDS_dataset->n_rows; i++) {
      ((unsigned short *)rawData)[i] *= factor;
    }
    break;
  }
  return(1);
}

SDDS_SetDataMode()

epicsShareFuncSDDS int32_t SDDS_SetDataMode ( SDDS_DATASET * SDDS_dataset, int32_t newmode )

extern

Sets the data mode (ASCII or Binary) for the SDDS dataset.

This function configures the data mode of the SDDS dataset to either ASCII or Binary. When setting to Binary mode with byte swapping (using -SDDS_BINARY), it adjusts the byte order based on the machine's endianness to ensure compatibility.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset whose data mode is to be set.
[in]	newmode	The desired data mode. Valid values are: SDDS_ASCII for ASCII mode. SDDS_BINARY for Binary mode. -SDDS_BINARY for Binary mode with byte swapping (for compatibility with systems like the sddsendian program).

Returns

• 1 on successful mode change.
• 0 if the mode is invalid, if the dataset is NULL, or if the dataset has already been written to and the mode cannot be changed.

Note

• Changing the data mode is only permitted if no data has been written to the dataset (i.e., page_number is 0 and n_rows_written is 0).
• When using -SDDS_BINARY, the function automatically determines the appropriate byte order based on the machine's endianness.

Warning

• Attempting to change the data mode after writing data to the dataset will result in an error.
• Ensure that the newmode parameter is correctly specified to prevent unintended behavior.

See also

SDDS_SetError, SDDS_IsBigEndianMachine, SDDS_BINARY, SDDS_ASCII

Definition at line 5023 of file SDDS_utils.c.

                                                                      {
  if (!SDDS_dataset) {
    SDDS_SetError("NULL page pointer (SDDS_SetDataMode)");
    return 0;
  }
  if (newmode == -SDDS_BINARY) {
    /* will write with bytes swapped.
       * provided for compatibility with sddsendian program, which writes the
       * data itself 
       */
    SDDS_dataset->layout.byteOrderDeclared = SDDS_IsBigEndianMachine() ? SDDS_LITTLEENDIAN : SDDS_BIGENDIAN;
    newmode = SDDS_BINARY;
  }
  if (newmode != SDDS_ASCII && newmode != SDDS_BINARY) {
    SDDS_SetError("Invalid data mode (SDDS_SetDataMode)");
    return 0;
  }
  if (newmode == SDDS_dataset->layout.data_mode.mode)
    return 1;
  if (SDDS_dataset->page_number != 0 && (SDDS_dataset->page_number > 1 || SDDS_dataset->n_rows_written != 0)) {
    SDDS_SetError("Can't change the mode of a file that's been written to (SDDS_SetDataMode)");
    return 0;
  }
  SDDS_dataset->layout.data_mode.mode = SDDS_dataset->original_layout.data_mode.mode = newmode;
  return 1;
}

SDDS_SetDefaultIOBufferSize()

epicsShareFuncSDDS int32_t SDDS_SetDefaultIOBufferSize ( int32_t newValue )

extern

Sets the default I/O buffer size used for file operations.

This function updates the global defaultIOBufferSize variable, which determines the size of the I/O buffer used for file read/write operations. The initial default is SDDS_FILEBUFFER_SIZE, which is 262144 bytes.

Parameters

newValue

The new default I/O buffer size in bytes. If newValue is negative, the function returns the current buffer size without changing it. If newValue is between 0 and 128 (inclusive), it is treated as 0, effectively disabling buffering.

Returns

The previous default I/O buffer size if newValue is greater than or equal to 0; otherwise, returns the current default buffer size without changing it.

Definition at line 82 of file SDDS_binary.c.

                                                      {
  int32_t previous;
  if (newValue < 0)
    return SDDS_GetLockedDefaultIOBufferSize();
  if (newValue < 128) /* arbitrary limit */
    newValue = 0;
  mdb_thread_lock(&defaultIOBufferSizeLock);
  previous = defaultIOBufferSize;
  defaultIOBufferSize = newValue;
  mdb_thread_unlock(&defaultIOBufferSizeLock);
  return previous;
}

SDDS_SetError()

epicsShareFuncSDDS void SDDS_SetError ( char * error_text )

extern

Records an error message in the SDDS error stack.

This function appends an error message to the internal error stack. These errors can later be retrieved and displayed using SDDS_PrintErrors.

Parameters

[in]

error_text

The error message to be recorded. If NULL, a warning is printed to stderr.

See also

SDDS_PrintErrors

SDDS_ClearErrors

Definition at line 421 of file SDDS_utils.c.

                                     {
  SDDS_SetError0(error_text);
  SDDS_SetError0("\n");
}

SDDS_SetError0()

epicsShareFuncSDDS void SDDS_SetError0 ( char * error_text )

extern

Internal function to record an error message in the SDDS error stack.

This function appends an error message to the internal error stack without adding additional formatting or line breaks. It is typically called by SDDS_SetError.

Parameters

[in]

error_text

The error message to be recorded. If NULL, a warning is printed to stderr.

Note

This function is intended for internal use within the SDDS library and should not be called directly by user code.

See also

SDDS_SetError

Definition at line 437 of file SDDS_utils.c.

                                      {
  if (n_errors >= n_errors_max) {
    if (!(error_description = SDDS_Realloc(error_description, (n_errors_max += 10) * sizeof(*error_description)))) {
      fputs("Error trying to allocate additional error description string (SDDS_SetError)\n", stderr);
      fprintf(stderr, "Most recent error text:\n%s\n", error_text);
      abort();
    }
  }
  if (!error_text)
    fprintf(stderr, "warning: error text is NULL (SDDS_SetError)\n");
  else {
    if (!SDDS_CopyString(&error_description[n_errors], error_text)) {
      fputs("Error trying to copy additional error description text (SDDS_SetError)\n", stderr);
      fprintf(stderr, "Most recent error text: %s\n", error_text);
      abort();
    }
    n_errors++;
  }
}

SDDS_SetLZMACompressionLevel()

epicsShareFuncSDDS void SDDS_SetLZMACompressionLevel ( int32_t level )

extern

Definition at line 83 of file SDDS_lzma.c.

                                                 {
  if (level >= 0 && level <= 9) {
    mdb_thread_lock(&lzmaCompressionLevelLock);
    lzmaCompressionLevel = level;
    mdb_thread_unlock(&lzmaCompressionLevelLock);
  }
}

SDDS_SetMemory()

epicsShareFuncSDDS int32_t SDDS_SetMemory ( void * mem, int64_t n_elements, int32_t data_type, ... )

extern

Initializes a memory block with a sequence of values based on a specified data type.

This function sets a block of memory to a sequence of values, starting from a specified initial value and incrementing by a defined delta. The sequence is determined by the data_type parameter, which specifies the type of each element in the memory block. The function supports various SDDS data types and handles the initialization accordingly.

Parameters

[in,out]	mem	Pointer to the memory block to be initialized.
[in]	n_elements	The number of elements to initialize in the memory block.
[in]	data_type	The SDDS data type of each element. Must be one of the following constants: SDDS_SHORT SDDS_USHORT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_FLOAT SDDS_DOUBLE SDDS_LONGDOUBLE SDDS_CHARACTER
[in]	...	Variable arguments specifying the starting value and increment value. The types of these arguments depend on the data_type: For integer types (SDDS_SHORT, SDDS_USHORT, SDDS_LONG, SDDS_ULONG, SDDS_LONG64, SDDS_ULONG64): First argument: initial value (int, unsigned int, int32_t, uint32_t, int64_t, uint64_t) Second argument: increment value (int, unsigned int, int32_t, uint32_t, int64_t, uint64_t) For floating-point types (SDDS_FLOAT, SDDS_DOUBLE, SDDS_LONGDOUBLE): First argument: initial value (double for float and double, long double for SDDS_LONGDOUBLE) Second argument: increment value (double for float and double, long double for SDDS_LONGDOUBLE) For SDDS_CHARACTER: First argument: initial value (char) Second argument: increment value (short)

Returns

Returns 1 on successful memory initialization. Returns 0 if an unknown or invalid data_type is provided.

Note

The function uses variable arguments to accept the starting and increment values. The caller must ensure that the correct types are provided based on the data_type parameter.

See also

SDDS_Malloc

SDDS_Free

Definition at line 2105 of file SDDS_utils.c.

{
  va_list argptr;
  int32_t retval;
  int64_t i;
  short short_val, short_dval, *short_ptr;
  unsigned short ushort_val, ushort_dval, *ushort_ptr;
  int32_t long_val, long_dval, *long_ptr;
  uint32_t ulong_val, ulong_dval, *ulong_ptr;
  int64_t long64_val, long64_dval, *long64_ptr;
  uint64_t ulong64_val, ulong64_dval, *ulong64_ptr;
  float float_val, float_dval, *float_ptr;
  double double_val, double_dval, *double_ptr;
  long double longdouble_val, longdouble_dval, *longdouble_ptr;
  char char_val, *char_ptr;
 
  retval = 1;
  va_start(argptr, data_type);
  switch (data_type) {
  case SDDS_SHORT:
    short_val = (short)va_arg(argptr, int);
    short_dval = (short)va_arg(argptr, int);
    short_ptr = (short *)mem;
    for (i = 0; i < n_elements; i++, short_val += short_dval)
      *short_ptr++ = short_val;
    break;
  case SDDS_USHORT:
    ushort_val = (unsigned short)va_arg(argptr, int);
    ushort_dval = (unsigned short)va_arg(argptr, int);
    ushort_ptr = (unsigned short *)mem;
    for (i = 0; i < n_elements; i++, ushort_val += ushort_dval)
      *ushort_ptr++ = ushort_val;
    break;
  case SDDS_LONG:
    long_val = (int32_t)va_arg(argptr, int32_t);
    long_dval = (int32_t)va_arg(argptr, int32_t);
    long_ptr = (int32_t *)mem;
    for (i = 0; i < n_elements; i++, long_val += long_dval)
      *long_ptr++ = long_val;
    break;
  case SDDS_ULONG:
    ulong_val = (uint32_t)va_arg(argptr, uint32_t);
    ulong_dval = (uint32_t)va_arg(argptr, uint32_t);
    ulong_ptr = (uint32_t *)mem;
    for (i = 0; i < n_elements; i++, ulong_val += ulong_dval)
      *ulong_ptr++ = ulong_val;
    break;
  case SDDS_LONG64:
    long64_val = (int64_t)va_arg(argptr, int64_t);
    long64_dval = (int64_t)va_arg(argptr, int64_t);
    long64_ptr = (int64_t *)mem;
    for (i = 0; i < n_elements; i++, long64_val += long64_dval)
      *long64_ptr++ = long64_val;
    break;
  case SDDS_ULONG64:
    ulong64_val = (uint64_t)va_arg(argptr, uint32_t);
    ulong64_dval = (uint64_t)va_arg(argptr, uint32_t);
    ulong64_ptr = (uint64_t *)mem;
    for (i = 0; i < n_elements; i++, ulong64_val += ulong64_dval)
      *ulong64_ptr++ = ulong64_val;
    break;
  case SDDS_FLOAT:
    float_val = (float)va_arg(argptr, double);
    float_dval = (float)va_arg(argptr, double);
    float_ptr = (float *)mem;
    for (i = 0; i < n_elements; i++, float_val += float_dval)
      *float_ptr++ = float_val;
    break;
  case SDDS_DOUBLE:
    double_val = (double)va_arg(argptr, double);
    double_dval = (double)va_arg(argptr, double);
    double_ptr = (double *)mem;
    for (i = 0; i < n_elements; i++, double_val += double_dval)
      *double_ptr++ = double_val;
    break;
  case SDDS_LONGDOUBLE:
    longdouble_val = (long double)va_arg(argptr, long double);
    longdouble_dval = (long double)va_arg(argptr, long double);
    longdouble_ptr = (long double *)mem;
    for (i = 0; i < n_elements; i++, longdouble_val += longdouble_dval)
      *longdouble_ptr++ = longdouble_val;
    break;
  case SDDS_CHARACTER:
    char_val = (char)va_arg(argptr, int);
    short_dval = (short)va_arg(argptr, int);
    char_ptr = (char *)mem;
    for (i = 0; i < n_elements; i++, char_val += short_dval)
      *char_ptr++ = char_val;
    break;
  default:
    SDDS_SetError("Unable to set memory--unknown or invalid data type (SDDS_SetMemory)");
    retval = 0;
    break;
  }
  va_end(argptr);
  return (retval);
}

SDDS_SetNameValidityFlags()

epicsShareFuncSDDS int32_t SDDS_SetNameValidityFlags ( uint32_t flags )

extern

Sets the validity flags for parameter and column names in the SDDS dataset.

This function allows the user to configure the rules for validating names of parameters and columns within the SDDS dataset. The validity flags determine the set of allowed characters and naming conventions.

Parameters

[in]

flags

A bitmask representing the desired name validity flags. Possible flags include: SDDS_ALLOW_ANY_NAME: Allows any name without restrictions. SDDS_ALLOW_V15_NAME: Enables compatibility with SDDS version 1.5 naming conventions. Additional flags as defined in the SDDS library.

Returns

• The previous name validity flags before the update.

Precondition

• The function can be called at any time before defining parameters or columns to influence name validation.

Postcondition

• The name validity flags are updated to reflect the specified rules.

Note

• Changing name validity flags affects how subsequent parameter and column names are validated.
• It is recommended to set the desired validity flags before defining any dataset elements to avoid validation errors.

Warning

• Improperly setting validity flags may lead to unintended acceptance or rejection of valid or invalid names.
• Ensure that the flags are set according to the desired naming conventions for your dataset.

Definition at line 2060 of file SDDS_output.c.

                                                  {
  uint32_t oldFlags;
  mdb_thread_lock(&nameValidityFlagsLock);
  oldFlags = nameValidityFlags;
  nameValidityFlags = flags;
  mdb_thread_unlock(&nameValidityFlagsLock);
  return oldFlags;
}

SDDS_SetNoRowCounts()

epicsShareFuncSDDS int32_t SDDS_SetNoRowCounts ( SDDS_DATASET * SDDS_dataset, int32_t value )

extern

Sets the flag to enable or disable row counts in the SDDS dataset.

This function configures the SDDS dataset to either include or exclude row counts in the output. Row counts provide metadata about the number of rows written, which can be useful for data integrity and validation. Disabling row counts can improve performance when such metadata is unnecessary.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure to be configured.
[in]	value	The flag value to set: 0: Enable row counts (default behavior). Non-zero: Disable row counts.

Returns

• 1 on successful configuration.
• 0 if an error occurred (e.g., attempting to change the flag after the layout has been written).

Precondition

• The SDDS_dataset must be initialized and not have written the layout yet.

Postcondition

• The dataset's configuration reflects the specified row count setting.

Note

• Changing the row count setting affects how data rows are managed and stored in the output file.

Warning

• This function cannot be called after the dataset layout has been written to the file or if the dataset is in read mode.
• Disabling row counts may complicate data validation and integrity checks.

Definition at line 854 of file SDDS_output.c.

                                                                       {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetNoRowCounts"))
    return 0;
  if (SDDS_dataset->layout.layout_written) {
    SDDS_SetError("Can't change no_row_counts after writing the layout, or for a file you are reading.");
    return 0;
  }
  SDDS_dataset->layout.data_mode.no_row_counts = value ? 1 : 0;
  return 1;
}

SDDS_SetParameter()

epicsShareFuncSDDS int32_t SDDS_SetParameter ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Sets the value of a single parameter in the current data table of an SDDS dataset.

This function assigns a value to a specified parameter in the current data table of the given SDDS dataset. It must be preceded by a call to SDDS_StartPage to initialize the table. The parameter to be set can be identified either by its index or by its name. The value can be passed either by value or by reference, depending on the specified mode.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	A bitwise combination of the following constants: SDDS_SET_BY_INDEX: Identify the parameter by its index. SDDS_SET_BY_NAME: Identify the parameter by its name. SDDS_PASS_BY_VALUE: Pass the parameter value by value. SDDS_PASS_BY_REFERENCE: Pass the parameter value by reference.

Mode Requirements:

• Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set.
• Exactly one of SDDS_PASS_BY_VALUE or SDDS_PASS_BY_REFERENCE must be set.

Syntax Based on Mode Combination:

• SDDS_SET_BY_INDEX + SDDS_PASS_BY_VALUE: int32_t SDDS_SetParameter(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t index, value)
• SDDS_SET_BY_INDEX + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetParameter(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t index, void *data)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_VALUE: int32_t SDDS_SetParameter(SDDS_DATASET *SDDS_dataset, int32_t mode, char *name, value)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetParameter(SDDS_DATASET *SDDS_dataset, int32_t mode, char *name, void *data)

Note: For parameters of type SDDS_STRING, passing by value means passing a char *, whereas passing by reference means passing a char **.

Returns

Returns 1 on successful assignment of the parameter value. On failure, returns 0 and records an appropriate error message.

See also

SDDS_StartPage, SDDS_SetError, SDDS_GetParameterIndex, SDDS_CopyString

Definition at line 539 of file SDDS_dataprep.c.

                                                                         {
  va_list argptr;
  int32_t index;
  SDDS_LAYOUT *layout;
  char *name;
  char s[SDDS_MAXLINE];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetParameters"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME) || !(mode & SDDS_PASS_BY_VALUE || mode & SDDS_PASS_BY_REFERENCE)) {
    SDDS_SetError("Unable to set parameter values--unknown mode (SDDS_SetParameters)");
    return (0);
  }
 
  va_start(argptr, mode);
  layout = &SDDS_dataset->layout;
 
  /* variable arguments are pairs of (index, value), where index is a int32_t integer */
  if (mode & SDDS_SET_BY_INDEX) {
    if ((index = va_arg(argptr, int32_t)) == -1) {
      SDDS_SetError("Unable to set parameter values--index is null (SDDS_SetParameter)");
      va_end(argptr);
      return (0);
    }
    if (index < 0 || index >= layout->n_parameters) {
      SDDS_SetError("Unable to set parameter values--index out of range (SDDS_SetParameter)");
      va_end(argptr);
      return (0);
    }
  } else {
    if ((name = va_arg(argptr, char *)) == NULL) {
      SDDS_SetError("Unable to set parameter values--name is null (SDDS_SetParameter)");
      va_end(argptr);
      return (0);
    }
    if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0) {
      sprintf(s, "Unable to set parameter values--name %s not recognized (SDDS_SetParameter)", name);
      SDDS_SetError(s);
      va_end(argptr);
      return (0);
    }
  }
  switch (layout->parameter_definition[index].type) {
  case SDDS_SHORT:
    if (mode & SDDS_PASS_BY_VALUE)
      *((short *)SDDS_dataset->parameter[index]) = (short)va_arg(argptr, int);
    else
      *((short *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, short *));
    break;
  case SDDS_USHORT:
    if (mode & SDDS_PASS_BY_VALUE)
      *((unsigned short *)SDDS_dataset->parameter[index]) = (unsigned short)va_arg(argptr, unsigned int);
    else
      *((unsigned short *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, unsigned short *));
    break;
  case SDDS_LONG:
    if (mode & SDDS_PASS_BY_VALUE)
      *((int32_t *)SDDS_dataset->parameter[index]) = (int32_t)va_arg(argptr, int32_t);
    else
      *((int32_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, int32_t *));
    break;
  case SDDS_ULONG:
    if (mode & SDDS_PASS_BY_VALUE)
      *((uint32_t *)SDDS_dataset->parameter[index]) = (uint32_t)va_arg(argptr, uint32_t);
    else
      *((uint32_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, uint32_t *));
    break;
  case SDDS_LONG64:
    if (mode & SDDS_PASS_BY_VALUE)
      *((int64_t *)SDDS_dataset->parameter[index]) = (int64_t)va_arg(argptr, int64_t);
    else
      *((int64_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, int64_t *));
    break;
  case SDDS_ULONG64:
    if (mode & SDDS_PASS_BY_VALUE)
      *((uint64_t *)SDDS_dataset->parameter[index]) = (uint64_t)va_arg(argptr, uint64_t);
    else
      *((uint64_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, uint64_t *));
    break;
  case SDDS_FLOAT:
    if (mode & SDDS_PASS_BY_VALUE)
      *((float *)SDDS_dataset->parameter[index]) = (float)va_arg(argptr, double);
    else
      *((float *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, float *));
    break;
  case SDDS_DOUBLE:
    if (mode & SDDS_PASS_BY_VALUE)
      *((double *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
    else
      *((double *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
    break;
  case SDDS_LONGDOUBLE:
    if (mode & SDDS_PASS_BY_VALUE)
      *((long double *)SDDS_dataset->parameter[index]) = va_arg(argptr, long double);
    else
      *((long double *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, long double *));
    break;
  case SDDS_STRING:
    if (*(char **)SDDS_dataset->parameter[index])
      free(*(char **)SDDS_dataset->parameter[index]);
    if (mode & SDDS_PASS_BY_VALUE) {
      if (!SDDS_CopyString((char **)SDDS_dataset->parameter[index], va_arg(argptr, char *))) {
        SDDS_SetError("Unable to set string parameter value--allocation failure (SDDS_SetParameters)");
        va_end(argptr);
        return (0);
      }
    } else {
      if (!SDDS_CopyString((char **)SDDS_dataset->parameter[index], *(va_arg(argptr, char **)))) {
        SDDS_SetError("Unable to set string parameter value--allocation failure (SDDS_SetParameters)");
        va_end(argptr);
        return (0);
      }
    }
    break;
  case SDDS_CHARACTER:
    if (mode & SDDS_PASS_BY_VALUE)
      *((char *)SDDS_dataset->parameter[index]) = (char)va_arg(argptr, int);
    else
      *((char *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, char *));
    break;
  default:
    SDDS_SetError("Unknown data type encountered (SDDS_SetParameters)");
    va_end(argptr);
    return (0);
  }
  va_end(argptr);
  return (1);
}

SDDS_SetParameters()

epicsShareFuncSDDS int32_t SDDS_SetParameters ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Sets the values of one or more parameters for the current data table in an SDDS dataset.

This function assigns values to parameters in the current data table of the specified SDDS dataset. It must be preceded by a call to SDDS_StartPage to initialize the table. The function can be called multiple times to set parameters for different tables, but SDDS_WriteTable should be used to write each table to disk.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	A bitwise combination of the following constants: SDDS_SET_BY_INDEX: Specify parameters by their index. SDDS_SET_BY_NAME: Specify parameters by their name. SDDS_PASS_BY_VALUE: Pass parameter values by value. SDDS_PASS_BY_REFERENCE: Pass parameter values by reference.

Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set to indicate how parameters are identified. Additionally, exactly one of SDDS_PASS_BY_VALUE or SDDS_PASS_BY_REFERENCE must be set to indicate how parameter values are provided.

The syntax for the four possible mode combinations is as follows:

• SDDS_SET_BY_INDEX + SDDS_PASS_BY_VALUE: int32_t SDDS_SetParameters(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t index1, value1, int32_t index2, value2, ..., -1)
• SDDS_SET_BY_INDEX + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetParameters(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t index1, void *data1, int32_t index2, void *data2, ..., -1)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_VALUE: int32_t SDDS_SetParameters(SDDS_DATASET *SDDS_dataset, int32_t mode, char *name1, value1, char *name2, value2, ..., NULL)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetParameters(SDDS_DATASET *SDDS_dataset, int32_t mode, char *name1, void *data1, char *name2, void *data2, ..., NULL)

Note: For parameters of type SDDS_STRING, passing by value means passing a char *, whereas passing by reference means passing a char **.

Returns

Returns 1 on success. On failure, returns 0 and records an error message.

See also

SDDS_StartPage, SDDS_WriteTable, SDDS_SetError, SDDS_GetParameterIndex, va_start, va_arg, va_end

Definition at line 375 of file SDDS_dataprep.c.

                                                                          {
  va_list argptr;
  int32_t index, retval;
  SDDS_LAYOUT *layout;
  char *name;
  char s[SDDS_MAXLINE];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetParameters"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME) || !(mode & SDDS_PASS_BY_VALUE || mode & SDDS_PASS_BY_REFERENCE)) {
    SDDS_SetError("Unable to set parameter values--unknown mode (SDDS_SetParameters)");
    return (0);
  }
 
  va_start(argptr, mode);
  layout = &SDDS_dataset->layout;
 
  /* variable arguments are pairs of (index, value), where index is a int32_t integer */
  retval = -1;
  do {
    if (mode & SDDS_SET_BY_INDEX) {
      if ((index = va_arg(argptr, int32_t)) == -1) {
        retval = 1;
        break;
      }
      if (index < 0 || index >= layout->n_parameters) {
        SDDS_SetError("Unable to set parameter values--index out of range (SDDS_SetParameters)");
        retval = 0;
        break;
      }
    } else {
      if ((name = va_arg(argptr, char *)) == NULL) {
        retval = 1;
        break;
      }
      if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0) {
        sprintf(s, "Unable to set parameter values--name %s not recognized (SDDS_SetParameters)", name);
        SDDS_SetError(s);
        retval = 0;
        break;
      }
    }
    switch (layout->parameter_definition[index].type) {
    case SDDS_SHORT:
      if (mode & SDDS_PASS_BY_VALUE)
        *((short *)SDDS_dataset->parameter[index]) = (short)va_arg(argptr, int);
      else
        *((short *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, short *));
      break;
    case SDDS_USHORT:
      if (mode & SDDS_PASS_BY_VALUE)
        *((unsigned short *)SDDS_dataset->parameter[index]) = (unsigned short)va_arg(argptr, unsigned int);
      else
        *((unsigned short *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, unsigned short *));
      break;
    case SDDS_LONG:
      if (mode & SDDS_PASS_BY_VALUE)
        *((int32_t *)SDDS_dataset->parameter[index]) = (int32_t)va_arg(argptr, int32_t);
      else
        *((int32_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, int32_t *));
      break;
    case SDDS_ULONG:
      if (mode & SDDS_PASS_BY_VALUE)
        *((uint32_t *)SDDS_dataset->parameter[index]) = (uint32_t)va_arg(argptr, uint32_t);
      else
        *((uint32_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, uint32_t *));
      break;
    case SDDS_LONG64:
      if (mode & SDDS_PASS_BY_VALUE)
        *((int64_t *)SDDS_dataset->parameter[index]) = (int64_t)va_arg(argptr, int64_t);
      else
        *((int64_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, int64_t *));
      break;
    case SDDS_ULONG64:
      if (mode & SDDS_PASS_BY_VALUE)
        *((uint64_t *)SDDS_dataset->parameter[index]) = (uint64_t)va_arg(argptr, uint64_t);
      else
        *((uint64_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, uint64_t *));
      break;
    case SDDS_FLOAT:
      if (mode & SDDS_PASS_BY_VALUE)
        *((float *)SDDS_dataset->parameter[index]) = (float)va_arg(argptr, double);
      else
        *((float *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, float *));
      break;
    case SDDS_DOUBLE:
      if (mode & SDDS_PASS_BY_VALUE)
        *((double *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((double *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_LONGDOUBLE:
      if (mode & SDDS_PASS_BY_VALUE)
        *((long double *)SDDS_dataset->parameter[index]) = va_arg(argptr, long double);
      else
        *((long double *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, long double *));
      break;
    case SDDS_STRING:
      if (*(char **)SDDS_dataset->parameter[index])
        free(*(char **)SDDS_dataset->parameter[index]);
      if (mode & SDDS_PASS_BY_VALUE) {
        if (!SDDS_CopyString((char **)SDDS_dataset->parameter[index], va_arg(argptr, char *))) {
          SDDS_SetError("Unable to set string parameter value--allocation failure (SDDS_SetParameters)");
          retval = 0;
        }
      } else {
        if (!SDDS_CopyString((char **)SDDS_dataset->parameter[index], *(va_arg(argptr, char **)))) {
          SDDS_SetError("Unable to set string parameter value--allocation failure (SDDS_SetParameters)");
          retval = 0;
        }
      }
      break;
    case SDDS_CHARACTER:
      if (mode & SDDS_PASS_BY_VALUE)
        *((char *)SDDS_dataset->parameter[index]) = (char)va_arg(argptr, int);
      else
        *((char *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, char *));
      break;
    default:
      SDDS_SetError("Unknown data type encountered (SDDS_SetParameters)");
      retval = 0;
    }
  } while (retval == -1);
  va_end(argptr);
  return (retval);
}

SDDS_SetParametersFromDoubles()

epicsShareFuncSDDS int32_t SDDS_SetParametersFromDoubles ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Sets the values of one or more parameters in the current data table of an SDDS dataset using double-precision floating-point numbers.

This function assigns double-precision floating-point values to specified parameters in the current data table of the given SDDS dataset. It must be preceded by a call to SDDS_StartPage to initialize the table. Parameters can be identified either by their index or by their name. The values can be passed either by value or by reference, depending on the specified mode.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	A bitwise combination of the following constants: SDDS_SET_BY_INDEX: Identify parameters by their indices. SDDS_SET_BY_NAME: Identify parameters by their names. SDDS_PASS_BY_VALUE: Pass parameter values by value. SDDS_PASS_BY_REFERENCE: Pass parameter values by reference.

Mode Requirements:

• Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set.
• Exactly one of SDDS_PASS_BY_VALUE or SDDS_PASS_BY_REFERENCE must be set.

Syntax Based on Mode Combination:

• SDDS_SET_BY_INDEX + SDDS_PASS_BY_VALUE: int32_t SDDS_SetParametersFromDoubles(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t index, double value)
• SDDS_SET_BY_INDEX + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetParametersFromDoubles(SDDS_DATASET *SDDS_dataset, int32_t mode, int32_t index, double *data)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_VALUE: int32_t SDDS_SetParametersFromDoubles(SDDS_DATASET *SDDS_dataset, int32_t mode, char *name, double value)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetParametersFromDoubles(SDDS_DATASET *SDDS_dataset, int32_t mode, char *name, double *data)

Note: For parameters of type SDDS_STRING, setting values using this function is not supported and will result in an error.

Returns

Returns 1 on successful assignment of all specified parameter values. On failure, returns 0 and records an appropriate error message.

See also

SDDS_StartPage, SDDS_SetError, SDDS_GetParameterIndex

Definition at line 703 of file SDDS_dataprep.c.

                                                                                     {
  va_list argptr;
  int32_t index, retval;
  SDDS_LAYOUT *layout;
  char *name;
  char s[SDDS_MAXLINE];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetParametersFromDoubles"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME) || !(mode & SDDS_PASS_BY_VALUE || mode & SDDS_PASS_BY_REFERENCE)) {
    SDDS_SetError("Unable to set parameter values--unknown mode (SDDS_SetParametersFromDoubles)");
    return (0);
  }
 
  va_start(argptr, mode);
  layout = &SDDS_dataset->layout;
 
  /* variable arguments are pairs of (index, value), where index is a int32_t integer */
  retval = -1;
  do {
    if (mode & SDDS_SET_BY_INDEX) {
      if ((index = va_arg(argptr, int32_t)) == -1) {
        retval = 1;
        break;
      }
      if (index < 0 || index >= layout->n_parameters) {
        sprintf(s, "Unable to set parameter values--index %" PRId32 " out of range [%d, %" PRId32 "] (SDDS_SetParametersFromDoubles)", index, 0, layout->n_parameters);
        SDDS_SetError(s);
        retval = 0;
        break;
      }
    } else {
      if ((name = va_arg(argptr, char *)) == NULL) {
        retval = 1;
        break;
      }
      if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) < 0) {
        sprintf(s, "Unable to set parameter values--name %s not recognized (SDDS_SetParametersFromDoubles)", name);
        SDDS_SetError(s);
        retval = 0;
        break;
      }
    }
    switch (layout->parameter_definition[index].type) {
    case SDDS_SHORT:
      if (mode & SDDS_PASS_BY_VALUE)
        *((short *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((short *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_USHORT:
      if (mode & SDDS_PASS_BY_VALUE)
        *((unsigned short *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((unsigned short *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_LONG:
      if (mode & SDDS_PASS_BY_VALUE)
        *((int32_t *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((int32_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_ULONG:
      if (mode & SDDS_PASS_BY_VALUE)
        *((uint32_t *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((uint32_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_LONG64:
      if (mode & SDDS_PASS_BY_VALUE)
        *((int64_t *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((int64_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_ULONG64:
      if (mode & SDDS_PASS_BY_VALUE)
        *((uint64_t *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((uint64_t *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_FLOAT:
      if (mode & SDDS_PASS_BY_VALUE)
        *((float *)SDDS_dataset->parameter[index]) = (float)va_arg(argptr, double);
      else
        *((float *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_DOUBLE:
      if (mode & SDDS_PASS_BY_VALUE)
        *((double *)SDDS_dataset->parameter[index]) = va_arg(argptr, double);
      else
        *((double *)SDDS_dataset->parameter[index]) = *(va_arg(argptr, double *));
      break;
    case SDDS_STRING:
    case SDDS_CHARACTER:
      SDDS_SetError("Nonnumeric data type encountered (SDDS_SetParametersFromDoubles)");
      retval = 0;
      break;
    default:
      SDDS_SetError("Unknown data type encountered (SDDS_SetParametersFromDoubles)");
      retval = 0;
    }
  } while (retval == -1);
  va_end(argptr);
  return (retval);
}

SDDS_SetParameterUnitsConversion()

epicsShareFuncSDDS int32_t SDDS_SetParameterUnitsConversion ( SDDS_DATASET * SDDS_dataset, char * parameter_name, char * new_units, char * old_units, double factor )

extern

Sets unit conversions for a specified parameter in an SDDS dataset.

This function updates the units of the specified parameter within the SDDS dataset and applies a conversion factor to its value if the dataset has already been read (i.e., pages_read > 0). The function ensures that the new units are consistent with the old units if provided.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
parameter_name	A null-terminated string specifying the name of the parameter to update.
new_units	A null-terminated string specifying the new units to assign to the parameter. This parameter must not be NULL.
old_units	A null-terminated string specifying the expected current units of the parameter. If NULL, the function does not verify the existing units.
factor	A double representing the conversion factor to apply to the parameter's value. The parameter's value will be multiplied by this factor.

Returns

Returns 1 on successful unit conversion and update. On failure, returns 0 and sets an appropriate error message.

Return values

1	Indicates that the unit conversion was successfully applied.
0	Indicates that an error occurred (e.g., invalid dataset, unrecognized parameter name, type undefined, memory allocation failure).

Note

• The new_units parameter must not be NULL. Passing NULL will result in an error.
• If the dataset has not been read yet (pages_read == 0), the conversion factor is stored but not applied immediately.
• The function handles various data types, ensuring that the conversion factor is appropriately applied based on the parameter's type.

See also

SDDS_SetArrayUnitsConversion, SDDS_SetColumnUnitsConversion, SDDS_GetParameter

Definition at line 4904 of file SDDS_extract.c.

                                                                                                                                             {
  int32_t index, type;
  void *rawData;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetParameterUnitsConversion"))
    return(0);
  if (new_units == NULL) {
    SDDS_SetError("new_units is NULL (SDDS_SetParameterUnitsConversion)");
    return(0);
  }
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, parameter_name)) < 0) {
    SDDS_SetError("Unable to get parameter--name is not recognized (SDDS_SetParameterUnitsConversion)");
    return(0);
  }
  if (!(type = SDDS_GetParameterType(SDDS_dataset, index))) {
    SDDS_SetError("Unable to get parameter--data type undefined (SDDS_SetParameterUnitsConversion)");
    return(0);
  }
  if (SDDS_dataset->layout.parameter_definition[index].units != NULL) {
    if (strcmp(new_units, SDDS_dataset->layout.parameter_definition[index].units) != 0) {
      if ((old_units != NULL) && (strcmp(old_units, SDDS_dataset->layout.parameter_definition[index].units) != 0)) {
        SDDS_SetError("Unexpected units value found (SDDS_SetParameterUnitsConversion)");
        return(0);
      }
      /* free(SDDS_dataset->layout.parameter_definition[index].units); */
      cp_str(&(SDDS_dataset->layout.parameter_definition[index].units), new_units);
    }
  } else {
    cp_str(&(SDDS_dataset->layout.parameter_definition[index].units), new_units);
  }
 
  if (SDDS_dataset->pages_read == 0) {
    return(1);
  }
  rawData = SDDS_dataset->parameter[index];
  switch (type) {
  case SDDS_LONGDOUBLE:
    *((long double *)rawData) *= factor;
    break;
  case SDDS_DOUBLE:
    *((double *)rawData) *= factor;
    break;
  case SDDS_FLOAT:
    *((float *)rawData) *= factor;
    break;
  case SDDS_LONG:
    *((int32_t *)rawData) *= factor;
    break;
  case SDDS_ULONG:
    *((uint32_t *)rawData) *= factor;
    break;
  case SDDS_LONG64:
    *((int64_t *)rawData) *= factor;
    break;
  case SDDS_ULONG64:
    *((uint64_t *)rawData) *= factor;
    break;
  case SDDS_SHORT:
    *((short *)rawData) *= factor;
    break;
  case SDDS_USHORT:
    *((unsigned short *)rawData) *= factor;
    break;
  }
  return(1);
}

SDDS_SetReadRecoveryMode()

epicsShareFuncSDDS void SDDS_SetReadRecoveryMode ( SDDS_DATASET * SDDS_dataset, int32_t mode )

extern

Sets the read recovery mode for an SDDS dataset.

This function configures whether read recovery is possible for the specified SDDS dataset. Enabling recovery allows the dataset to attempt to recover partial data in case of read errors.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
mode	Integer flag indicating the recovery mode: 0 to disable read recovery. 1 to enable read recovery.

The function updates the readRecoveryPossible flag within the dataset structure based on the provided mode parameter. This flag is later checked by other functions to determine whether to attempt data recovery after encountering read errors.

Note

• Enabling read recovery does not guarantee that all data can be recovered after an error.
• It is recommended to enable recovery only if partial data recovery is acceptable in your application.

Definition at line 2103 of file SDDS_binary.c.

                                                                        {
  SDDS_dataset->readRecoveryPossible = mode;
}

SDDS_SetRowCountMode()

epicsShareFuncSDDS int32_t SDDS_SetRowCountMode ( SDDS_DATASET * SDDS_dataset, uint32_t mode )

extern

Sets the row count mode for the SDDS dataset.

This function configures how row counts are managed within the SDDS dataset. The row count mode determines whether row counts are variable, fixed, or entirely omitted during data writing. Proper configuration of row count modes can enhance data integrity and performance based on specific use cases.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	mode	The row count mode to be set. Must be one of the following: SDDS_VARIABLEROWCOUNT: Enables variable row counts, allowing the number of rows to vary. SDDS_FIXEDROWCOUNT: Sets a fixed row count mode, where the number of rows is constant. SDDS_NOROWCOUNT: Disables row counts, omitting them from the dataset.

Returns

• 1 on successful configuration of the row count mode.
• 0 on failure, with an error message set internally.

Precondition

• The dataset must be initialized and configured for output.
• The layout must not have been written to the file yet.

Postcondition

• The dataset's row count mode is updated according to the specified mode.

Note

• Changing the row count mode affects how row metadata is handled during data writing.
• The SDDS_FIXEDROWCOUNT mode may require specifying additional parameters such as row increment.

Warning

• Attempting to change the row count mode after the layout has been written to the file or while reading from a file will result in an error.
• Selecting an invalid row count mode will result in an error.

Definition at line 2346 of file SDDS_output.c.

                                                                        {
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetRowCountMode"))
    return 0;
  if (SDDS_dataset->layout.layout_written) {
    SDDS_SetError("Can't change row count mode after writing the layout, or for a file you are reading.");
    return 0;
  }
  if (mode & SDDS_VARIABLEROWCOUNT) {
    SDDS_dataset->layout.data_mode.fixed_row_count = 0;
    SDDS_dataset->layout.data_mode.no_row_counts = 0;
  } else if (mode & SDDS_FIXEDROWCOUNT) {
    SDDS_dataset->layout.data_mode.fixed_row_count = 1;
    SDDS_dataset->layout.data_mode.fixed_row_increment = 500;
    SDDS_dataset->layout.data_mode.no_row_counts = 0;
    SDDS_dataset->layout.data_mode.fsync_data = 0;
  } else if (mode & SDDS_NOROWCOUNT) {
    SDDS_dataset->layout.data_mode.fixed_row_count = 0;
    SDDS_dataset->layout.data_mode.no_row_counts = 1;
  } else {
    SDDS_SetError("Invalid row count mode (SDDS_SetRowCountMode).");
    return 0;
  }
  if (!SDDS_SaveLayout(SDDS_dataset))
    return 0;
  return 1;
}

SDDS_SetRowFlags()

epicsShareFuncSDDS int32_t SDDS_SetRowFlags ( SDDS_DATASET * SDDS_dataset, int32_t row_flag_value )

extern

Sets the acceptance flags for all rows in the current data table of a data set.

This function initializes the acceptance flags for each row in the data table. A non-zero flag indicates that the row is "of interest" and should be considered in subsequent operations, while a zero flag marks the row for rejection.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
row_flag_value	Integer value to assign to all row flags. Non-zero value: Marks rows as accepted ("of interest"). Zero value: Marks rows as rejected.

Returns

• 1 on successful update of row flags.
• 0 on failure, with an error message recorded.

Note

This function overwrites any existing row flags with the specified row_flag_value.

See also

SDDS_GetRowFlag, SDDS_GetRowFlags

Definition at line 46 of file SDDS_extract.c.

                                                                             {
  /*  int32_t i; */
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetRowFlags"))
    return (0);
  if (!SDDS_SetMemory(SDDS_dataset->row_flag, SDDS_dataset->n_rows_allocated, SDDS_LONG, (int32_t)row_flag_value, (int32_t)0)) {
    SDDS_SetError("Unable to set row flags--memory filling failed (SDDS_SetRowFlags)");
    return (0);
  }
  return (1);
}

SDDS_SetRowLimit()

epicsShareFuncSDDS int64_t SDDS_SetRowLimit ( int64_t limit )

extern

Sets the row limit for the SDDS dataset.

Parameters

limit

The maximum number of rows to read. If limit <= 0, the row limit is set to INT64_MAX.

Returns

The previous row limit value.

Definition at line 1243 of file SDDS_input.c.

                                        {
  int64_t previous;
  if (limit <= 0)
    limit = INT64_MAX;
  mdb_thread_lock(&SDDS_RowLimitLock);
  previous = SDDS_RowLimit;
  SDDS_RowLimit = limit;
  mdb_thread_unlock(&SDDS_RowLimitLock);
  return previous;
}

SDDS_SetRowsOfInterest()

epicsShareFuncSDDS int64_t SDDS_SetRowsOfInterest ( SDDS_DATASET * SDDS_dataset, char * selection_column, int32_t mode, ... )

extern

Sets the rows of interest in an SDDS dataset based on various selection criteria.

This function marks rows in the provided SDDS dataset as "of interest" based on the specified selection criteria. It supports multiple selection modes, allowing users to specify rows by an array of names, a single string containing multiple names, a variadic list of names, or by matching a specific string with logical operations.

Calling Modes:

• SDDS_NAME_ARRAY: Specify an array of names.

  SDDS_SetRowsOfInterest(&SDDS_dataset, selection_column, SDDS_NAME_ARRAY, int32_t n_entries, char **name);

• SDDS_NAMES_STRING: Provide a single string containing multiple names separated by delimiters.

  SDDS_SetRowsOfInterest(&SDDS_dataset, selection_column, SDDS_NAMES_STRING, char *names);

• SDDS_NAME_STRINGS: Pass multiple name strings, terminated by NULL.

  SDDS_SetRowsOfInterest(&SDDS_dataset, selection_column, SDDS_NAME_STRINGS, char *name1, char *name2, ..., NULL);

• SDDS_MATCH_STRING: Match rows based on a single string and logical operations.

  SDDS_SetRowsOfInterest(&SDDS_dataset, selection_column, SDDS_MATCH_STRING, char *name, int32_t logic_mode);

Additionally, each of these modes has a case-insensitive variant prefixed with SDDS_CI_ (e.g., SDDS_CI_NAME_ARRAY).

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
selection_column	A null-terminated string specifying the name of the column used for row selection. This column must be of string type.
mode	An integer representing the selection mode. Supported modes include: SDDS_NAME_ARRAY SDDS_NAMES_STRING SDDS_NAME_STRINGS SDDS_MATCH_STRING SDDS_CI_NAME_ARRAY SDDS_CI_NAMES_STRING SDDS_CI_NAME_STRINGS SDDS_CI_MATCH_STRING
...	Variable arguments corresponding to the selected mode: SDDS_NAME_ARRAY and SDDS_CI_NAME_ARRAY: int32_t n_entries: Number of names. char **name: Array of name strings. SDDS_NAMES_STRING and SDDS_CI_NAMES_STRING: char *names: Single string containing multiple names separated by delimiters. SDDS_NAME_STRINGS and SDDS_CI_NAME_STRINGS: char *name1, char *name2, ..., NULL: Multiple name strings terminated by NULL. SDDS_MATCH_STRING and SDDS_CI_MATCH_STRING: char *name: String to match. int32_t logic_mode: Logical operation mode.

Returns

On success, returns the number of rows marked as "of interest". On failure, returns -1 and sets an appropriate error message.

Return values

-1	Indicates that an error occurred (e.g., invalid dataset, unrecognized selection column, memory allocation failure, unknown mode).
Non-negative	Integer representing the count of rows marked as "of interest".

Note

• The caller must ensure that the selection_column exists and is of string type in the dataset.
• For modes that allocate memory internally (e.g., SDDS_NAMES_STRING), the function handles memory management internally.

See also

SDDS_MatchRowsOfInterest, SDDS_FilterRowsOfInterest, SDDS_DeleteUnsetRows

Definition at line 3325 of file SDDS_extract.c.

{
  va_list argptr;
  int32_t retval, type, index, n_names;
  int64_t i, j;
  char **name, *string, *match_string, *ptr;
  int32_t local_memory; /* (0,1,2) --> (none, pointer array, pointer array + strings) locally allocated */
  char buffer[SDDS_MAXLINE];
  int32_t logic, caseSensitive;
  int64_t count;
 
  name = NULL;
  n_names = local_memory = logic = 0;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetRowsOfInterest"))
    return (-1);
  va_start(argptr, mode);
  retval = 1;
  caseSensitive = 1;
  match_string = NULL;
  switch (mode) {
  case SDDS_CI_NAME_ARRAY:
    caseSensitive = 0;
  case SDDS_NAME_ARRAY:
    local_memory = 0;
    n_names = va_arg(argptr, int32_t);
    name = va_arg(argptr, char **);
    break;
  case SDDS_CI_NAMES_STRING:
    caseSensitive = 0;
  case SDDS_NAMES_STRING:
    local_memory = 2;
    n_names = 0;
    name = NULL;
    ptr = va_arg(argptr, char *);
    SDDS_CopyString(&string, ptr);
    while (SDDS_GetToken(string, buffer, SDDS_MAXLINE) > 0) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1))) || !SDDS_CopyString(name + n_names, buffer)) {
        SDDS_SetError("Unable to process row selection--memory allocation failure (SDDS_SetRowsOfInterest)");
        retval = -1;
        break;
      }
      n_names++;
    }
    free(string);
    break;
  case SDDS_CI_NAME_STRINGS:
    caseSensitive = 0;
  case SDDS_NAME_STRINGS:
    local_memory = 1;
    n_names = 0;
    name = NULL;
    while ((string = va_arg(argptr, char *))) {
      if (!(name = SDDS_Realloc(name, sizeof(*name) * (n_names + 1)))) {
        SDDS_SetError("Unable to process row selection--memory allocation failure (SDDS_SetRowsOfInterest)");
        retval = -1;
        break;
      }
      name[n_names++] = string;
    }
    break;
  case SDDS_CI_MATCH_STRING:
    caseSensitive = 0;
  case SDDS_MATCH_STRING:
    local_memory = 0;
    n_names = 1;
    if ((string = va_arg(argptr, char *)))
      match_string = expand_ranges(string);
    logic = va_arg(argptr, int32_t);
    if (logic & SDDS_NOCASE_COMPARE)
      caseSensitive = 0;
    break;
  default:
    SDDS_SetError("Unable to process row selection--unknown mode (SDDS_SetRowsOfInterest)");
    retval = -1;
    break;
  }
 
  va_end(argptr);
  if (retval != 1)
    return (-1);
 
  if (mode != SDDS_MATCH_STRING && mode != SDDS_CI_MATCH_STRING) {
    int (*stringCompare)(const char *s1, const char *s2);
    if (caseSensitive)
      stringCompare = strcmp;
    else
      stringCompare = strcmp_ci;
    if ((index = SDDS_GetColumnIndex(SDDS_dataset, selection_column)) < 0) {
      SDDS_SetError("Unable to process row selection--unrecognized selection column name (SDDS_SetRowsOfInterest)");
      return (-1);
    }
    if ((type = SDDS_GetColumnType(SDDS_dataset, index)) != SDDS_STRING) {
      SDDS_SetError("Unable to select rows--selection column is not string type (SDDS_SetRowsOfInterest)");
      return (-1);
    }
    if (n_names == 0) {
      SDDS_SetError("Unable to process row selection--no names in call (SDDS_SetRowsOfInterest)");
      return (-1);
    }
    for (j = 0; j < n_names; j++) {
      for (i = 0; i < SDDS_dataset->n_rows; i++) {
        if ((*stringCompare)(*((char **)SDDS_dataset->data[index] + i), name[j]) == 0)
          SDDS_dataset->row_flag[i] = 1;
      }
    }
  } else {
    if (selection_column) {
      int (*wildMatch)(char *string, char *template);
      if (caseSensitive)
        wildMatch = wild_match;
      else
        wildMatch = wild_match_ci;
      if (!match_string) {
        SDDS_SetError("Unable to select rows--no matching string given (SDDS_SetRowsOfInterest)");
        return (-1);
      }
      if ((index = SDDS_GetColumnIndex(SDDS_dataset, selection_column)) < 0) {
        free(match_string);
        SDDS_SetError("Unable to process row selection--unrecognized selection column name (SDDS_SetRowsOfInterest)");
        return (-1);
      }
      if ((type = SDDS_GetColumnType(SDDS_dataset, index)) != SDDS_STRING) {
        free(match_string);
        SDDS_SetError("Unable to select rows--selection column is not string type (SDDS_SetRowsOfInterest)");
        return (-1);
      }
      for (i = 0; i < SDDS_dataset->n_rows; i++)
        SDDS_dataset->row_flag[i] = SDDS_Logic(SDDS_dataset->row_flag[i], (*wildMatch)(*((char **)SDDS_dataset->data[index] + i), match_string), logic);
    } else {
      for (i = 0; i < SDDS_dataset->n_rows; i++)
        SDDS_dataset->row_flag[i] = SDDS_Logic(SDDS_dataset->row_flag[i], 0, logic & ~(SDDS_AND | SDDS_OR));
    }
  }
 
  if (local_memory == 2) {
    for (i = 0; i < n_names; i++)
      free(name[i]);
  }
  if (match_string)
    free(match_string);
  if (local_memory >= 1)
    free(name);
 
  for (i = count = 0; i < SDDS_dataset->n_rows; i++)
    if (SDDS_dataset->row_flag[i])
      count++;
  return (count);
}

SDDS_SetRowValues()

epicsShareFuncSDDS int32_t SDDS_SetRowValues ( SDDS_DATASET * SDDS_dataset, int32_t mode, int64_t row, ... )

extern

Sets the values of one or more columns in a specified row of the current data table of an SDDS dataset.

This function assigns values to specified columns in a particular row of the current data table within the given SDDS dataset. It must be preceded by a call to SDDS_StartPage to initialize the table. Columns can be identified either by their index or by their name. The values can be passed either by value or by reference, depending on the specified mode.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
mode	A bitwise combination of the following constants: SDDS_SET_BY_INDEX: Identify columns by their indices. SDDS_SET_BY_NAME: Identify columns by their names. SDDS_PASS_BY_VALUE: Pass column values by value. SDDS_PASS_BY_REFERENCE: Pass column values by reference.

Mode Requirements:

• Exactly one of SDDS_SET_BY_INDEX or SDDS_SET_BY_NAME must be set.
• Exactly one of SDDS_PASS_BY_VALUE or SDDS_PASS_BY_REFERENCE must be set.

Syntax Based on Mode Combination:

• SDDS_SET_BY_INDEX + SDDS_PASS_BY_VALUE: int32_t SDDS_SetRowValues(SDDS_DATASET *SDDS_dataset, int32_t mode, int64_t row, int32_t index, value, ..., -1)
• SDDS_SET_BY_INDEX + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetRowValues(SDDS_DATASET *SDDS_dataset, int32_t mode, int64_t row, int32_t index, void *data, ..., -1)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_VALUE: int32_t SDDS_SetRowValues(SDDS_DATASET *SDDS_dataset, int32_t mode, int64_t row, char *name, value, ..., NULL)
• SDDS_SET_BY_NAME + SDDS_PASS_BY_REFERENCE: int32_t SDDS_SetRowValues(SDDS_DATASET *SDDS_dataset, int32_t mode, int64_t row, char *name, void *data, ..., NULL)

Note: For columns of type SDDS_STRING, passing by value means passing a char *, whereas passing by reference means passing a char **.

Parameters

row	The row number in the data table where the column values will be set. Row numbering starts from 1.

Returns

Returns 1 on successful assignment of all specified column values. On failure, returns 0 and records an appropriate error message.

See also

SDDS_StartPage, SDDS_SetError, SDDS_GetColumnIndex, SDDS_CopyString

Definition at line 994 of file SDDS_dataprep.c.

                                                                                      {
  va_list argptr;
  int32_t index;
  int32_t retval;
  SDDS_LAYOUT *layout;
  char *name;
  char buffer[200];
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_SetRowValues"))
    return (0);
  if (!(mode & SDDS_SET_BY_INDEX || mode & SDDS_SET_BY_NAME) || !(mode & SDDS_PASS_BY_VALUE || mode & SDDS_PASS_BY_REFERENCE)) {
    SDDS_SetError("Unable to set column values--unknown mode (SDDS_SetRowValues)");
    return (0);
  }
  if (!SDDS_CheckTabularData(SDDS_dataset, "SDDS_SetRowValues"))
    return (0);
  row -= SDDS_dataset->first_row_in_mem;
  if (row >= SDDS_dataset->n_rows_allocated) {
    sprintf(buffer, "Unable to set column values--row number (%" PRId64 ") exceeds exceeds allocated memory (%" PRId64 ") (SDDS_SetRowValues)", row, SDDS_dataset->n_rows_allocated);
    SDDS_SetError(buffer);
    return (0);
  }
  if (row > SDDS_dataset->n_rows - 1)
    SDDS_dataset->n_rows = row + 1;
 
  va_start(argptr, row);
  layout = &SDDS_dataset->layout;
 
  /* variable arguments are pairs of (index, value), where index is a int32_t integer */
  retval = -1;
#ifdef DEBUG
  fprintf(stderr, "setting row %" PRId64 " (mem slot %" PRId64 ")\n", row + SDDS_dataset->first_row_in_mem, row);
#endif
  do {
    if (mode & SDDS_SET_BY_INDEX) {
      if ((index = va_arg(argptr, int32_t)) == -1) {
        retval = 1;
        break;
      }
      if (index < 0 || index >= layout->n_columns) {
        SDDS_SetError("Unable to set column values--index out of range (SDDS_SetRowValues)");
        retval = 0;
        break;
      }
#ifdef DEBUG
      fprintf(stderr, "Setting values for column #%" PRId32 "\n", index);
#endif
    } else {
      if ((name = va_arg(argptr, char *)) == NULL) {
        retval = 1;
        break;
      }
#ifdef DEBUG
      fprintf(stderr, "Setting values for column %s\n", name);
#endif
      if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) < 0) {
        SDDS_SetError("Unable to set column values--name not recognized (SDDS_SetRowValues)");
        retval = 0;
        break;
      }
    }
    switch (layout->column_definition[index].type) {
    case SDDS_SHORT:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((short *)SDDS_dataset->data[index]) + row) = (short)va_arg(argptr, int);
      else
        *(((short *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, short *));
      break;
    case SDDS_USHORT:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((unsigned short *)SDDS_dataset->data[index]) + row) = (unsigned short)va_arg(argptr, unsigned int);
      else
        *(((unsigned short *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, unsigned short *));
      break;
    case SDDS_LONG:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((int32_t *)SDDS_dataset->data[index]) + row) = va_arg(argptr, int32_t);
      else
        *(((int32_t *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, int32_t *));
      break;
    case SDDS_ULONG:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((uint32_t *)SDDS_dataset->data[index]) + row) = va_arg(argptr, uint32_t);
      else
        *(((uint32_t *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, uint32_t *));
      break;
    case SDDS_LONG64:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((int64_t *)SDDS_dataset->data[index]) + row) = va_arg(argptr, int64_t);
      else
        *(((int64_t *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, int64_t *));
      break;
    case SDDS_ULONG64:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((uint64_t *)SDDS_dataset->data[index]) + row) = va_arg(argptr, uint64_t);
      else
        *(((uint64_t *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, uint64_t *));
      break;
    case SDDS_FLOAT:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((float *)SDDS_dataset->data[index]) + row) = (float)va_arg(argptr, double);
      else
        *(((float *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, float *));
      break;
    case SDDS_DOUBLE:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((double *)SDDS_dataset->data[index]) + row) = va_arg(argptr, double);
      else
        *(((double *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, double *));
      break;
    case SDDS_LONGDOUBLE:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((long double *)SDDS_dataset->data[index]) + row) = va_arg(argptr, long double);
      else
        *(((long double *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, long double *));
      break;
    case SDDS_STRING:
      if (((char **)SDDS_dataset->data[index])[row]) {
        free(((char **)SDDS_dataset->data[index])[row]);
        ((char **)SDDS_dataset->data[index])[row] = NULL;
      }
      if (mode & SDDS_PASS_BY_VALUE) {
        if (!SDDS_CopyString((char **)SDDS_dataset->data[index] + row, va_arg(argptr, char *))) {
          SDDS_SetError("Unable to set string column value--allocation failure (SDDS_SetRowValues)");
          retval = 0;
        }
      } else {
        if (!SDDS_CopyString((char **)SDDS_dataset->data[index] + row, *(va_arg(argptr, char **)))) {
          SDDS_SetError("Unable to set string column value--allocation failure (SDDS_SetRowValues)");
          retval = 0;
        }
      }
      break;
    case SDDS_CHARACTER:
      if (mode & SDDS_PASS_BY_VALUE)
        *(((char *)SDDS_dataset->data[index]) + row) = (char)va_arg(argptr, int);
      else
        *(((char *)SDDS_dataset->data[index]) + row) = *(va_arg(argptr, char *));
      break;
    default:
      SDDS_SetError("Unknown data type encountered (SDDS_SetRowValues");
      retval = 0;
      break;
    }
  } while (retval == -1);
  va_end(argptr);
  return (retval);
}

SDDS_SetTerminateMode()

epicsShareFuncSDDS void SDDS_SetTerminateMode ( uint32_t mode )

extern

Sets the terminate mode for the SDDS dataset.

Parameters

mode	The terminate mode to set.

Definition at line 1359 of file SDDS_input.c.

                                          {
  mdb_thread_lock(&terminateModeLock);
  terminateMode = mode;
  mdb_thread_unlock(&terminateModeLock);
}

SDDS_ShortenTable()

epicsShareFuncSDDS int32_t SDDS_ShortenTable ( SDDS_DATASET * SDDS_dataset, int64_t rows )

extern

Shortens the data table in the SDDS dataset to a specified number of rows.

This function reduces the number of allocated rows in the specified SDDS dataset to the given rows count. It reallocates memory for each column's data array and the row flags, freeing existing data as necessary. All data is reset, and the number of rows is set to zero.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure whose table will be shortened.
rows	The new number of rows to allocate in the table. If rows is less than or equal to zero, it defaults to 1.

Returns

Returns 1 on successful reallocation and initialization. On failure, returns 0 and records an error message.

See also

SDDS_Realloc, SDDS_SetMemory, SDDS_Free, SDDS_SetError

Definition at line 244 of file SDDS_dataprep.c.

                                                                    {
  SDDS_LAYOUT *layout;
  int64_t i, size;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_ShortenTable"))
    return (0);
  layout = &SDDS_dataset->layout;
  if (!SDDS_dataset->data && !(SDDS_dataset->data = (void **)calloc(layout->n_columns, sizeof(*SDDS_dataset->data)))) {
    SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_ShortenTable)");
    return (0);
  }
  if (rows <= 0)
    rows = 1;
  for (i = 0; i < layout->n_columns; i++) {
    size = SDDS_type_size[layout->column_definition[i].type - 1];
    if (SDDS_dataset->data[i])
      free(SDDS_dataset->data[i]);
    if (!(SDDS_dataset->data[i] = (void *)calloc(rows, size))) {
      SDDS_SetError("Unable to shorten page--memory allocation failure (SDDS_ShortenTable)");
      return (0);
    }
  }
  if (SDDS_dataset->row_flag)
    free(SDDS_dataset->row_flag);
  if (!(SDDS_dataset->row_flag = (int32_t *)malloc(rows * sizeof(int32_t)))) {
    SDDS_SetError("Unable to shorten page--memory allocation failure (SDDS_ShortenTable)");
    return (0);
  }
  SDDS_dataset->n_rows_allocated = rows;
  /* Shorten table is not exactly true. It is really deleting all the rows and then allocating new space.
     if (SDDS_dataset->n_rows > rows) {
     SDDS_dataset->n_rows = rows;
     }
  */
  SDDS_dataset->n_rows = 0;
 
  if (!SDDS_SetMemory(SDDS_dataset->row_flag, SDDS_dataset->n_rows_allocated, SDDS_LONG, (int32_t)1, (int32_t)0) ||
      !SDDS_SetMemory(SDDS_dataset->column_flag, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)1, (int32_t)0) || 
      !SDDS_SetMemory(SDDS_dataset->column_order, SDDS_dataset->layout.n_columns, SDDS_LONG, (int32_t)0, (int32_t)1)) {
    SDDS_SetError("Unable to shorten page--memory initialization failure (SDDS_ShortenTable)");
    return (0);
  }
  return (1);
}

SDDS_SprintTypedValue()

epicsShareFuncSDDS int32_t SDDS_SprintTypedValue ( void * data, int64_t index, int32_t type, const char * format, char * buffer, uint32_t mode )

extern

Formats a data value of a specified type into a string buffer using an optional printf format string.

This function formats a single data value from a data array into a provided buffer. It is a wrapper for SDDS_SprintTypedValueFactor with a default scaling factor of 1.0.

Parameters

[in]	data	Pointer to the base address of the data array containing the value to be formatted.
[in]	index	The index of the item within the data array to be formatted.
[in]	type	The data type of the value, specified by one of the SDDS constants: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_LONG64 SDDS_ULONG64 SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	format	(Optional) NULL-terminated string specifying a printf format. If NULL, a default format is used based on the data type.
[out]	buffer	Pointer to a character array where the formatted string will be stored.
[in]	mode	Flags controlling the formatting behavior. Valid values are: 0: Default behavior. SDDS_PRINT_NOQUOTES: When formatting strings, do not enclose them in quotes.

Returns

Returns 1 on success. On failure, returns 0 and records an error message.

Note

This function uses a default scaling factor of 1.0.

See also

SDDS_SprintTypedValueFactor

SDDS_SetError

Definition at line 161 of file SDDS_utils.c.

                                                                                                                        {
  return SDDS_SprintTypedValueFactor(data, index, type, format, buffer, mode, 1.0);
}

SDDS_SprintTypedValueFactor()

epicsShareFuncSDDS int32_t SDDS_SprintTypedValueFactor ( void * data, int64_t index, int32_t type, const char * format, char * buffer, uint32_t mode, double factor )

extern

Reallocates memory to a new size and zero-initializes the additional space.

This function extends the standard realloc functionality by zero-initializing any newly allocated memory beyond the original size. It ensures that memory is consistently reallocated and initialized across different build configurations.

Parameters

[in]	data	Pointer to the base address of the data array containing the value to be formatted.
[in]	index	The index of the item within the data array to be formatted.
[in]	type	The data type of the value, specified by one of the SDDS constants: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_ULONG SDDS_SHORT SDDS_USHORT SDDS_CHARACTER SDDS_STRING
[in]	format	(Optional) NULL-terminated string specifying a printf format. If NULL, a default format is used based on the data type.
[out]	buffer	Pointer to a character array where the formatted string will be stored.
[in]	mode	Flags controlling the formatting behavior. Valid values are: 0: Default behavior. SDDS_PRINT_NOQUOTES: When formatting strings, do not enclose them in quotes.
[in]	factor	Scaling factor to be applied to the value before formatting. The value is multiplied by this factor.

Returns

Returns 1 on success. On failure, returns 0 and records an error message.

Note

This function handles string types by optionally enclosing them in quotes, unless SDDS_PRINT_NOQUOTES is specified in mode.

See also

SDDS_SprintTypedValue

SDDS_SetError

Definition at line 196 of file SDDS_utils.c.

                                                                                                                                             {
  char buffer2[SDDS_PRINT_BUFLEN], *s;
  short printed;
 
  if (!data) {
    SDDS_SetError("Unable to print value--data pointer is NULL (SDDS_SprintTypedValueFactor)");
    return (0);
  }
  if (!buffer) {
    SDDS_SetError("Unable to print value--buffer pointer is NULL (SDDS_SprintTypedValueFactor)");
    return (0);
  }
  switch (type) {
  case SDDS_SHORT:
    sprintf(buffer, format ? format : "%hd", (short)(*((short *)data + index) * (factor)));
    break;
  case SDDS_USHORT:
    sprintf(buffer, format ? format : "%hu", (unsigned short)(*((unsigned short *)data + index) * (factor)));
    break;
  case SDDS_LONG:
    sprintf(buffer, format ? format : "%" PRId32, (int32_t)(*((int32_t *)data + index) * (factor)));
    break;
  case SDDS_ULONG:
    sprintf(buffer, format ? format : "%" PRIu32, (uint32_t)(*((uint32_t *)data + index) * (factor)));
    break;
  case SDDS_LONG64:
    sprintf(buffer, format ? format : "%" PRId64, (int64_t)(*((int64_t *)data + index) * (factor)));
    break;
  case SDDS_ULONG64:
    sprintf(buffer, format ? format : "%" PRIu64, (uint64_t)(*((uint64_t *)data + index) * (factor)));
    break;
  case SDDS_FLOAT:
    sprintf(buffer, format ? format : "%15.8e", (float)(*((float *)data + index) * (factor)));
    break;
  case SDDS_DOUBLE:
    sprintf(buffer, format ? format : "%21.15e", (double)(*((double *)data + index) * (factor)));
    break;
  case SDDS_LONGDOUBLE:
    if (LDBL_DIG == 18) {
      sprintf(buffer, format ? format : "%21.18Le", (long double)(*((long double *)data + index) * (factor)));
    } else {
      sprintf(buffer, format ? format : "%21.15Le", (long double)(*((long double *)data + index) * (factor)));
    }
    break;
  case SDDS_STRING:
    s = *((char **)data + index);
    if ((int32_t)strlen(s) > SDDS_PRINT_BUFLEN - 3) {
      SDDS_SetError("Buffer size overflow (SDDS_SprintTypedValue)");
      return (0);
    }
    if (!(mode & SDDS_PRINT_NOQUOTES)) {
      printed = 0;
      if (!s || SDDS_StringIsBlank(s))
        sprintf(buffer, "\"\"");
      else if (strchr(s, '"')) {
        strcpy(buffer2, s);
        SDDS_EscapeQuotes(buffer2, '"');
        if (SDDS_HasWhitespace(buffer2))
          sprintf(buffer, "\"%s\"", buffer2);
        else
          strcpy(buffer, buffer2);
      } else if (SDDS_HasWhitespace(s))
        sprintf(buffer, "\"%s\"", s);
      else {
        sprintf(buffer, format ? format : "%s", s);
        printed = 1;
      }
      if (!printed) {
        sprintf(buffer2, format ? format : "%s", buffer);
        strcpy(buffer, buffer2);
      }
    } else {
      sprintf(buffer, format ? format : "%s", s);
    }
    break;
  case SDDS_CHARACTER:
    sprintf(buffer, format ? format : "%c", *((char *)data + index));
    break;
  default:
    SDDS_SetError("Unable to print value--unknown data type (SDDS_SprintTypedValue)");
    return (0);
  }
  return (1);
}

SDDS_StartPage()

epicsShareFuncSDDS int32_t SDDS_StartPage ( SDDS_DATASET * SDDS_dataset, int64_t expected_n_rows )

extern

Initializes an SDDS_DATASET structure in preparation for inserting data into a new table.

This function prepares the specified SDDS dataset for data insertion by initializing necessary data structures and allocating memory based on the expected number of rows. It must be preceded by a call to SDDS_InitializeOutput. SDDS_StartPage can be called multiple times to begin writing additional tables within the dataset. After initializing a page, SDDS_WriteTable should be used to write the table to disk.

Parameters

SDDS_dataset	Pointer to the SDDS_DATASET structure representing the data set.
expected_n_rows	The expected number of rows in the data table. This value is used to preallocate memory for storing data values. If expected_n_rows is less than or equal to zero, it defaults to 1.

Returns

Returns 1 on successful initialization. On failure, returns 0 and records an error message.

See also

SDDS_InitializeOutput, SDDS_WriteTable, SDDS_SetError

Definition at line 70 of file SDDS_dataprep.c.

                                                                            {
  SDDS_LAYOUT *layout;
  int64_t i;
  int32_t size;
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_StartPage"))
    return (0);
  if ((SDDS_dataset->writing_page) && (SDDS_dataset->layout.data_mode.fixed_row_count)) {
    if (!SDDS_UpdateRowCount(SDDS_dataset))
      return (0);
  }
  if (!SDDS_RestoreLayout(SDDS_dataset)) {
    SDDS_SetError("Unable to start page--couldn't restore layout (SDDS_StartPage)");
    return (0);
  }
  if (expected_n_rows <= 0)
    expected_n_rows = 1;
  SDDS_dataset->n_rows_written = 0;
  SDDS_dataset->last_row_written = -1;
  SDDS_dataset->writing_page = 0;
  SDDS_dataset->first_row_in_mem = 0;
  layout = &SDDS_dataset->layout;
  if (SDDS_dataset->page_started == 0) {
    if (layout->n_parameters) {
      if (!(SDDS_dataset->parameter = (void **)calloc(sizeof(*SDDS_dataset->parameter), layout->n_parameters))) {
        SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
        return (0);
      }
      for (i = 0; i < layout->n_parameters; i++) {
        if (!(SDDS_dataset->parameter[i] = (void *)calloc(SDDS_type_size[layout->parameter_definition[i].type - 1], 1))) {
          SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
          return (0);
        }
      }
    }
    if (layout->n_arrays) {
      if (!(SDDS_dataset->array = (SDDS_ARRAY *)calloc(sizeof(*SDDS_dataset->array), layout->n_arrays))) {
        SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
        return (0);
      }
    }
    if (layout->n_columns) {
      if (!(SDDS_dataset->data = (void **)calloc(sizeof(*SDDS_dataset->data), layout->n_columns))) {
        SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
        return (0);
      }
      SDDS_dataset->row_flag = NULL;
      if (expected_n_rows) {
        if (!(SDDS_dataset->row_flag = (int32_t *)SDDS_Malloc(sizeof(int32_t) * expected_n_rows))) {
          SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
          return (0);
        }
        for (i = 0; i < layout->n_columns; i++) {
          if (!(SDDS_dataset->data[i] = (void *)calloc(expected_n_rows, SDDS_type_size[layout->column_definition[i].type - 1]))) {
            SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
            return (0);
          }
        }
      }
      SDDS_dataset->n_rows_allocated = expected_n_rows;
      if (!(SDDS_dataset->column_flag = (int32_t *)SDDS_Realloc(SDDS_dataset->column_flag, sizeof(int32_t) * layout->n_columns)) || 
          !(SDDS_dataset->column_order = (int32_t *)SDDS_Realloc(SDDS_dataset->column_order, sizeof(int32_t) * layout->n_columns))) {
        SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
        return (0);
      }
    }
  } else if (SDDS_dataset->n_rows_allocated >= expected_n_rows && layout->n_columns) {
    for (i = 0; i < layout->n_columns; i++) {
      if (SDDS_dataset->data[i] && layout->column_definition[i].type == SDDS_STRING)
        SDDS_FreeStringArray(SDDS_dataset->data[i], SDDS_dataset->n_rows_allocated);
    }
  } else if (SDDS_dataset->n_rows_allocated < expected_n_rows && layout->n_columns) {
    if (!SDDS_dataset->data) {
      if (!(SDDS_dataset->column_flag = (int32_t *)SDDS_Realloc(SDDS_dataset->column_flag, sizeof(int32_t) * layout->n_columns)) ||
          !(SDDS_dataset->column_order = (int32_t *)SDDS_Realloc(SDDS_dataset->column_order, sizeof(int32_t) * layout->n_columns)) || 
          !(SDDS_dataset->data = (void **)calloc(layout->n_columns, sizeof(*SDDS_dataset->data)))) {
        SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
        return (0);
      }
    }
    for (i = 0; i < layout->n_columns; i++) {
      size = SDDS_type_size[layout->column_definition[i].type - 1];
      if (SDDS_dataset->data[i] && layout->column_definition[i].type == SDDS_STRING)
        SDDS_FreeStringArray(SDDS_dataset->data[i], SDDS_dataset->n_rows_allocated);
      if (!(SDDS_dataset->data[i] = (void *)SDDS_Realloc(SDDS_dataset->data[i], expected_n_rows * size))) {
        SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
        return (0);
      }
      SDDS_ZeroMemory((char *)SDDS_dataset->data[i] + size * SDDS_dataset->n_rows_allocated, size * (expected_n_rows - SDDS_dataset->n_rows_allocated));
    }
    if (!(SDDS_dataset->row_flag = (int32_t *)SDDS_Realloc(SDDS_dataset->row_flag, sizeof(int32_t) * expected_n_rows))) {
      SDDS_SetError("Unable to start  page--memory allocation failure (SDDS_StartPage)");
      return (0);
    }
    SDDS_dataset->n_rows_allocated = expected_n_rows;
  }
  if (SDDS_dataset->n_rows_allocated && layout->n_columns && !SDDS_SetMemory(SDDS_dataset->row_flag, SDDS_dataset->n_rows_allocated, SDDS_LONG, (int32_t)1, (int32_t)0)) {
    SDDS_SetError("Unable to start page--memory initialization failure (SDDS_StartPage)");
    return (0);
  }
  if (layout->n_columns && (!SDDS_SetMemory(SDDS_dataset->column_flag, layout->n_columns, SDDS_LONG, (int32_t)1, (int32_t)0) || 
                            !SDDS_SetMemory(SDDS_dataset->column_order, layout->n_columns, SDDS_LONG, (int32_t)0, (int32_t)1))) {
    SDDS_SetError("Unable to start page--memory initialization failure (SDDS_StartPage)");
    return (0);
  }
  SDDS_dataset->n_of_interest = layout->n_columns;
  SDDS_dataset->page_number++;
  SDDS_dataset->page_started = 1;
  SDDS_dataset->n_rows = 0;
  return (1);
}

SDDS_StringIsBlank()

epicsShareFuncSDDS int32_t SDDS_StringIsBlank ( char * s )

extern

Checks if a string is blank (contains only whitespace characters).

This function determines whether the provided NULL-terminated string s consists solely of whitespace characters. If the string is NULL or contains only whitespace, the function returns 1. If the string contains any non-whitespace characters, it returns 0.

Parameters

[in]

s

Pointer to the NULL-terminated string to be checked.

Returns

• Returns 1 if the string is NULL or contains only whitespace characters.
• Returns 0 if the string contains any non-whitespace characters.

See also

isspace

Definition at line 2470 of file SDDS_utils.c.

                                    {
  if (!s)
    return 1;
  while (*s)
    if (!isspace(*s++))
      return (0);
  return (1);
}

SDDS_SwapDouble()

void SDDS_SwapDouble

(

double *

data

)

Swaps the endianness of a double.

This function swaps the byte order of a 64-bit double-precision floating-point number pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the double whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned double.

Definition at line 4083 of file SDDS_binary.c.

                                   {
  double copy;
  short i, j;
  copy = *data;
  for (i = 0, j = 7; i < 8; i++, j--)
    *(((char *)data) + i) = *(((char *)&copy) + j);
}

SDDS_SwapEndsArrayData()

epicsShareFuncSDDS int32_t SDDS_SwapEndsArrayData ( SDDS_DATASET * SDDSin )

extern

Swaps the endianness of the array data in an SDDS dataset.

This function iterates through all arrays defined in the specified SDDS dataset and swaps the byte order of each element to match the system's native endianness. It supports various data types including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. The function ensures that binary data is correctly interpreted on systems with different byte orders.

Parameters

[in,out]

SDDSin

Pointer to the SDDS_DATASET structure representing the dataset whose array data endianness is to be swapped.

Returns

int32_t Always returns 1.

Return values

1	The endianness of all applicable array data elements was successfully swapped.

Note

This function modifies the dataset's array data in place. It should be called only when the dataset's byte order is known to differ from the system's native byte order.

Definition at line 3872 of file SDDS_binary.c.

                                                     {
  int32_t i, j;
  SDDS_LAYOUT *layout;
  short *sData;
  unsigned short *suData;
  int32_t *lData;
  uint32_t *luData;
  int64_t *lData64;
  uint64_t *luData64;
  float *fData;
  double *dData;
  long double *ldData;
 
  layout = &SDDSin->layout;
 
  for (i = 0; i < layout->n_arrays; i++) {
    switch (layout->array_definition[i].type) {
    case SDDS_SHORT:
      sData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapShort(sData + j);
      break;
    case SDDS_USHORT:
      suData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapUShort(suData + j);
      break;
    case SDDS_LONG:
      lData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapLong(lData + j);
      break;
    case SDDS_ULONG:
      luData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapULong(luData + j);
      break;
    case SDDS_LONG64:
      lData64 = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapLong64(lData64 + j);
      break;
    case SDDS_ULONG64:
      luData64 = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapULong64(luData64 + j);
      break;
    case SDDS_LONGDOUBLE:
      ldData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapLongDouble(ldData + j);
      break;
    case SDDS_DOUBLE:
      dData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapDouble(dData + j);
      break;
    case SDDS_FLOAT:
      fData = SDDSin->array[i].data;
      for (j = 0; j < SDDSin->array[i].elements; j++)
        SDDS_SwapFloat(fData + j);
      break;
    default:
      break;
    }
  }
  return (1);
}

SDDS_SwapEndsColumnData()

epicsShareFuncSDDS int32_t SDDS_SwapEndsColumnData ( SDDS_DATASET * SDDSin )

extern

Swaps the endianness of the column data in an SDDS dataset.

This function iterates through all columns in the specified SDDS dataset and swaps the byte order of each data element to match the system's native endianness. It supports various data types, including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. The function ensures that binary data is correctly interpreted on systems with different byte orders.

Parameters

[in,out]

SDDSin

Pointer to the SDDS_DATASET structure representing the dataset whose column data endianness is to be swapped.

Returns

int32_t Always returns 1.

Return values

1	The endianness of all applicable column data elements was successfully swapped.

Note

This function modifies the dataset's column data in place. It should be called only when the dataset's byte order is known to differ from the system's native byte order. String data types are not affected by this function.

Definition at line 3707 of file SDDS_binary.c.

                                                      {
  int32_t i, row;
  SDDS_LAYOUT *layout;
  short *sData;
  unsigned short *suData;
  int32_t *lData;
  uint32_t *luData;
  int64_t *lData64;
  uint64_t *luData64;
  float *fData;
  double *dData;
  long double *ldData;
 
  layout = &SDDSin->layout;
  for (i = 0; i < layout->n_columns; i++) {
    switch (layout->column_definition[i].type) {
    case SDDS_SHORT:
      sData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapShort(sData + row);
      break;
    case SDDS_USHORT:
      suData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapUShort(suData + row);
      break;
    case SDDS_LONG:
      lData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapLong(lData + row);
      break;
    case SDDS_ULONG:
      luData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapULong(luData + row);
      break;
    case SDDS_LONG64:
      lData64 = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapLong64(lData64 + row);
      break;
    case SDDS_ULONG64:
      luData64 = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapULong64(luData64 + row);
      break;
    case SDDS_LONGDOUBLE:
      ldData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapLongDouble(ldData + row);
      break;
    case SDDS_DOUBLE:
      dData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapDouble(dData + row);
      break;
    case SDDS_FLOAT:
      fData = SDDSin->data[i];
      for (row = 0; row < SDDSin->n_rows; row++)
        SDDS_SwapFloat(fData + row);
      break;
    default:
      break;
    }
  }
  return (1);
}

SDDS_SwapEndsParameterData()

epicsShareFuncSDDS int32_t SDDS_SwapEndsParameterData ( SDDS_DATASET * SDDSin )

extern

Swaps the endianness of the parameter data in an SDDS dataset.

This function iterates through all parameters in the specified SDDS dataset and swaps the byte order of each data element to match the system's native endianness. It handles various data types, including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. Parameters with fixed values are skipped as their byte order is already consistent.

Parameters

[in,out]

SDDSin

Pointer to the SDDS_DATASET structure representing the dataset whose parameter data endianness is to be swapped.

Returns

int32_t Always returns 1.

Return values

1	The endianness of all applicable parameter data elements was successfully swapped.

Note

This function modifies the dataset's parameter data in place. It should be called only when the dataset's byte order is known to differ from the system's native byte order. String data types and parameters with fixed values are not affected by this function.

Definition at line 3793 of file SDDS_binary.c.

                                                         {
  int32_t i;
  SDDS_LAYOUT *layout;
  short *sData;
  unsigned short *suData;
  int32_t *lData;
  uint32_t *luData;
  int64_t *lData64;
  uint64_t *luData64;
  float *fData;
  double *dData;
  long double *ldData;
 
  layout = &SDDSin->layout;
  for (i = 0; i < layout->n_parameters; i++) {
    if (layout->parameter_definition[i].fixed_value) {
      continue;
    }
    switch (layout->parameter_definition[i].type) {
    case SDDS_SHORT:
      sData = SDDSin->parameter[i];
      SDDS_SwapShort(sData);
      break;
    case SDDS_USHORT:
      suData = SDDSin->parameter[i];
      SDDS_SwapUShort(suData);
      break;
    case SDDS_LONG:
      lData = SDDSin->parameter[i];
      SDDS_SwapLong(lData);
      break;
    case SDDS_ULONG:
      luData = SDDSin->parameter[i];
      SDDS_SwapULong(luData);
      break;
    case SDDS_LONG64:
      lData64 = SDDSin->parameter[i];
      SDDS_SwapLong64(lData64);
      break;
    case SDDS_ULONG64:
      luData64 = SDDSin->parameter[i];
      SDDS_SwapULong64(luData64);
      break;
    case SDDS_LONGDOUBLE:
      ldData = SDDSin->parameter[i];
      SDDS_SwapLongDouble(ldData);
      break;
    case SDDS_DOUBLE:
      dData = SDDSin->parameter[i];
      SDDS_SwapDouble(dData);
      break;
    case SDDS_FLOAT:
      fData = SDDSin->parameter[i];
      SDDS_SwapFloat(fData);
      break;
    default:
      break;
    }
  }
  return (1);
}

SDDS_SwapFloat()

void SDDS_SwapFloat

(

float *

data

)

Swaps the endianness of a float.

This function swaps the byte order of a 32-bit floating-point number pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the float whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned float.

Definition at line 4064 of file SDDS_binary.c.

                                 {
  float copy;
  short i, j;
  copy = *data;
  for (i = 0, j = 3; i < 4; i++, j--)
    *(((char *)data) + i) = *(((char *)&copy) + j);
}

SDDS_SwapLong()

epicsShareFuncSDDS void SDDS_SwapLong ( int32_t * data )

extern

Swaps the endianness of a 32-bit integer.

This function swaps the byte order of a 32-bit integer pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the 32-bit integer whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned 32-bit integer.

Definition at line 3988 of file SDDS_binary.c.

                                  {
  int32_t copy;
  short i, j;
  copy = *data;
  for (i = 0, j = 3; i < 4; i++, j--)
    *(((char *)data) + i) = *(((char *)&copy) + j);
}

SDDS_SwapLong64()

epicsShareFuncSDDS void SDDS_SwapLong64 ( int64_t * data )

extern

Swaps the endianness of a 64-bit integer.

This function swaps the byte order of a 64-bit integer pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the 64-bit integer whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned 64-bit integer.

Definition at line 4026 of file SDDS_binary.c.

                                    {
  int64_t copy;
  short i, j;
  copy = *data;
  for (i = 0, j = 7; i < 8; i++, j--)
    *(((char *)data) + i) = *(((char *)&copy) + j);
}

SDDS_SwapLongDouble()

void SDDS_SwapLongDouble

(

long double *

data

)

Swaps the endianness of a long double.

This function swaps the byte order of a long double floating-point number pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats. The function accounts for different sizes of long double based on the system's architecture.

Parameters

[in,out]

data

Pointer to the long double whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned long double. The size of long double may vary between different systems.

Definition at line 4103 of file SDDS_binary.c.

                                            {
  long double copy;
  short i, j;
  copy = *data;
  if (LDBL_DIG == 18) {
    for (i = 0, j = 11; i < 12; i++, j--)
      *(((char *)data) + i) = *(((char *)&copy) + j);
  } else {
    for (i = 0, j = 7; i < 8; i++, j--)
      *(((char *)data) + i) = *(((char *)&copy) + j);
  }
}

SDDS_SwapShort()

void SDDS_SwapShort

(

short *

data

)

Swaps the endianness of a short integer.

This function swaps the byte order of a 16-bit short integer pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the short integer whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned 16-bit short integer.

Definition at line 3952 of file SDDS_binary.c.

                                 {
  unsigned char c1;
  c1 = *((char *)data);
  *((char *)data) = *(((char *)data) + 1);
  *(((char *)data) + 1) = c1;
}

SDDS_SwapULong()

epicsShareFuncSDDS void SDDS_SwapULong ( uint32_t * data )

extern

Swaps the endianness of a 32-bit unsigned integer.

This function swaps the byte order of a 32-bit unsigned integer pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the 32-bit unsigned integer whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned 32-bit unsigned integer.

Definition at line 4007 of file SDDS_binary.c.

                                    {
  uint32_t copy;
  short i, j;
  copy = *data;
  for (i = 0, j = 3; i < 4; i++, j--)
    *(((char *)data) + i) = *(((char *)&copy) + j);
}

SDDS_SwapULong64()

epicsShareFuncSDDS void SDDS_SwapULong64 ( uint64_t * data )

extern

Swaps the endianness of a 64-bit unsigned integer.

This function swaps the byte order of a 64-bit unsigned integer pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the 64-bit unsigned integer whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned 64-bit unsigned integer.

Definition at line 4045 of file SDDS_binary.c.

                                      {
  uint64_t copy;
  short i, j;
  copy = *data;
  for (i = 0, j = 7; i < 8; i++, j--)
    *(((char *)data) + i) = *(((char *)&copy) + j);
}

SDDS_SwapUShort()

void SDDS_SwapUShort

(

unsigned short *

data

)

Swaps the endianness of an unsigned short integer.

This function swaps the byte order of a 16-bit unsigned short integer pointed to by the provided data pointer. It effectively converts the data between little-endian and big-endian formats.

Parameters

[in,out]

data

Pointer to the unsigned short integer whose byte order is to be swapped.

Note

The function modifies the data in place. Ensure that the pointer is valid and points to a properly aligned 16-bit unsigned short integer.

Definition at line 3970 of file SDDS_binary.c.

                                           {
  unsigned char c1;
  c1 = *((char *)data);
  *((char *)data) = *(((char *)data) + 1);
  *(((char *)data) + 1) = c1;
}

SDDS_SyncDataSet()

epicsShareFuncSDDS int32_t SDDS_SyncDataSet ( SDDS_DATASET * SDDS_dataset )

extern

Synchronizes the SDDS dataset with the disk by flushing buffered data.

This function attempts to ensure that any buffered data associated with the SDDS dataset is written to the disk using the fsync system call. However, on certain platforms such as VxWorks, Windows, Linux, and macOS, this functionality is not implemented and the function simply returns success. This behavior should be considered when relying on data synchronization across different operating systems.

Parameters

[in]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• 0 on success, indicating that data synchronization is either not needed or was successful.
• A negative value (e.g., -1) on failure to synchronize the data, with an error message set internally.

Note

• On unsupported platforms, the function does not perform any synchronization and returns success.
• The synchronization behavior depends on the operating system and its support for the fsync system call.

Warning

• On platforms where synchronization is not implemented, relying on this function for data integrity is not possible.
• Ensure that critical data is handled appropriately, considering the limitations of the target operating system.

Definition at line 1340 of file SDDS_output.c.

                                                     {
#if defined(vxWorks) || defined(_WIN32) || defined(linux) || defined(__APPLE__)
  return (0);
#else
  if (!(SDDS_dataset->layout.fp)) {
    SDDS_SetError("Unable to sync file--file pointer is NULL (SDDS_SyncDataSet)");
    return (-1);
  }
  if (SDDS_dataset->layout.data_mode.fsync_data == 0)
    return (0);
  if (fsync(fileno(SDDS_dataset->layout.fp)) == 0)
    return (0);
  /*
    SDDS_SetError("Unable to sync file (SDDS_SyncDataSet)");
    return(-1);
  */
  /* This error should not be fatal */
  return (0);
#endif
}

SDDS_Terminate()

epicsShareFuncSDDS int32_t SDDS_Terminate ( SDDS_DATASET * SDDS_dataset )

extern

Closes an SDDS file and frees the related memory.

Parameters

SDDS_dataset

A pointer to an SDDS dataset.

Returns

1 on success, 0 on error.

Definition at line 1471 of file SDDS_input.c.

                                                   {
  SDDS_LAYOUT *layout;
  char **ptr;
  int64_t i, j;
  FILE *fp;
  char termBuffer[16384];
  int32_t terminateMode;
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io)
    return SDDS_MPI_Terminate(SDDS_dataset);
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_Terminate"))
    return (0);
  layout = &SDDS_dataset->original_layout;
  terminateMode = SDDS_GetTerminateMode();
 
  fp = SDDS_dataset->layout.fp;
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (SDDS_dataset->layout.gzfp && layout->filename) {
      if ((SDDS_dataset->writing_page) && (SDDS_dataset->layout.data_mode.fixed_row_count)) {
        if (!SDDS_UpdateRowCount(SDDS_dataset))
          return (0);
      }
      gzclose(SDDS_dataset->layout.gzfp);
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (SDDS_dataset->layout.lzmafp && layout->filename) {
        if ((SDDS_dataset->writing_page) && (SDDS_dataset->layout.data_mode.fixed_row_count)) {
          if (!SDDS_UpdateRowCount(SDDS_dataset))
            return (0);
        }
        lzma_close(SDDS_dataset->layout.lzmafp);
      }
    } else {
      if (fp && layout->filename) {
        if ((SDDS_dataset->writing_page) && (SDDS_dataset->layout.data_mode.fixed_row_count)) {
          if (!SDDS_UpdateRowCount(SDDS_dataset))
            return (0);
        }
        if (layout->popenUsed) {
          while (fread(termBuffer, sizeof(*termBuffer), 16384, fp)) {
          }
#if defined(vxWorks)
          fprintf(stderr, "pclose is not supported in vxWorks\n");
          exit(1);
#else
        pclose(fp);
#endif
        } else {
          fclose(fp);
        }
      }
    }
#if defined(zLib)
  }
#endif
 
#if DEBUG
  fprintf(stderr, "Freeing data for file %s\n", SDDS_dataset->layout.filename ? SDDS_dataset->layout.filename : "NULL");
#endif
 
  if (SDDS_dataset->pagecount_offset)
    free(SDDS_dataset->pagecount_offset);
  if (SDDS_dataset->row_flag)
    free(SDDS_dataset->row_flag);
  if (SDDS_dataset->column_order)
    free(SDDS_dataset->column_order);
  if (SDDS_dataset->column_flag)
    free(SDDS_dataset->column_flag);
  if (SDDS_dataset->fBuffer.buffer)
    free(SDDS_dataset->fBuffer.buffer);
#if DEBUG
  fprintf(stderr, "freeing parameter data...\n");
#endif
  if (SDDS_dataset->parameter) {
    for (i = 0; i < layout->n_parameters; i++) {
      if (layout->parameter_definition[i].type == SDDS_STRING && *(char **)(SDDS_dataset->parameter[i]))
        free(*(char **)(SDDS_dataset->parameter[i]));
      if (SDDS_dataset->parameter[i])
        free(SDDS_dataset->parameter[i]);
    }
    free(SDDS_dataset->parameter);
  }
#if DEBUG
  fprintf(stderr, "freeing array data...\n");
#endif
  if (SDDS_dataset->array) {
    for (i = 0; i < layout->n_arrays; i++) {
      if (layout->array_definition[i].type == SDDS_STRING && !(terminateMode & TERMINATE_DONT_FREE_ARRAY_STRINGS)) {
        for (j = 0; j < SDDS_dataset->array[i].elements; j++)
          if (((char **)SDDS_dataset->array[i].data)[j])
            free(((char **)SDDS_dataset->array[i].data)[j]);
      }
      /*
            if (SDDS_dataset->array[i].definition->type==SDDS_STRING &&
            !(SDDS_GetTerminateMode()&TERMINATE_DONT_FREE_ARRAY_STRINGS)) {
            for (j=0; j<SDDS_dataset->array[i].elements; j++)
            if (((char**)SDDS_dataset->array[i].data)[j])
            free(((char**)SDDS_dataset->array[i].data)[j]);
            }
          */
      if (SDDS_dataset->array[i].data)
        free(SDDS_dataset->array[i].data);
      /* should free the subpointers too, but it would be a lot of trouble for little benefit: */
      if (SDDS_dataset->array[i].pointer && SDDS_dataset->array[i].definition->dimensions != 1)
        free(SDDS_dataset->array[i].pointer);
      if (SDDS_dataset->array[i].dimension)
        free(SDDS_dataset->array[i].dimension);
      /* don't touch this--it's done below */
      if (SDDS_dataset->array[i].definition && SDDS_dataset->array[i].definition->name) {
        if (SDDS_dataset->array[i].definition->name != layout->array_definition[i].name)
          SDDS_FreeArrayDefinition(SDDS_dataset->array[i].definition);
      }
      SDDS_dataset->array[i].definition = NULL;
    }
    free(SDDS_dataset->array);
  }
#if DEBUG
  fprintf(stderr, "freeing tabular data...\n");
#endif
  if (SDDS_dataset->data) {
    for (i = 0; i < layout->n_columns; i++)
      if (SDDS_dataset->data[i]) {
        if ((SDDS_dataset->column_track_memory == NULL) || (SDDS_dataset->column_track_memory[i])) {
          if (layout->column_definition[i].type == SDDS_STRING && !(terminateMode & TERMINATE_DONT_FREE_TABLE_STRINGS)) {
            ptr = (char **)SDDS_dataset->data[i];
            for (j = 0; j < SDDS_dataset->n_rows_allocated; j++, ptr++)
              if (*ptr)
                free(*ptr);
          }
          free(SDDS_dataset->data[i]);
        }
      }
    free(SDDS_dataset->data);
  }
  if (SDDS_dataset->column_track_memory)
    free(SDDS_dataset->column_track_memory);
#if DEBUG
  fprintf(stderr, "freeing layout data...\n");
#endif
  if (layout->description)
    free(layout->description);
  if (layout->contents == (&SDDS_dataset->layout)->contents)
    (&SDDS_dataset->layout)->contents = NULL;
  if (layout->contents)
    free(layout->contents);
  if (layout->filename)
    free(layout->filename);
  if (layout->column_definition) {
    for (i = 0; i < layout->n_columns; i++) {
      if (layout->column_index[i])
        free(layout->column_index[i]);
      if (layout->column_definition[i].name)
        free(layout->column_definition[i].name);
      if (layout->column_definition[i].symbol)
        free(layout->column_definition[i].symbol);
      if (layout->column_definition[i].units)
        free(layout->column_definition[i].units);
      if (layout->column_definition[i].description)
        free(layout->column_definition[i].description);
      if (layout->column_definition[i].format_string)
        free(layout->column_definition[i].format_string);
    }
    free(layout->column_definition);
    free(layout->column_index);
  }
  if (layout->parameter_definition) {
    for (i = 0; i < layout->n_parameters; i++) {
      if (layout->parameter_index[i])
        free(layout->parameter_index[i]);
      if (layout->parameter_definition[i].name)
        free(layout->parameter_definition[i].name);
      if (layout->parameter_definition[i].symbol)
        free(layout->parameter_definition[i].symbol);
      if (layout->parameter_definition[i].units)
        free(layout->parameter_definition[i].units);
      if (layout->parameter_definition[i].description)
        free(layout->parameter_definition[i].description);
      if (layout->parameter_definition[i].format_string)
        free(layout->parameter_definition[i].format_string);
      if (layout->parameter_definition[i].fixed_value)
        free(layout->parameter_definition[i].fixed_value);
    }
    free(layout->parameter_definition);
    free(layout->parameter_index);
  }
  if (layout->array_definition) {
    for (i = 0; i < layout->n_arrays; i++) {
      if (layout->array_index[i])
        free(layout->array_index[i]);
      if (layout->array_definition[i].name)
        free(layout->array_definition[i].name);
      if (layout->array_definition[i].symbol)
        free(layout->array_definition[i].symbol);
      if (layout->array_definition[i].units)
        free(layout->array_definition[i].units);
      if (layout->array_definition[i].description)
        free(layout->array_definition[i].description);
      if (layout->array_definition[i].format_string)
        free(layout->array_definition[i].format_string);
      if (layout->array_definition[i].group_name)
        free(layout->array_definition[i].group_name);
    }
    free(layout->array_definition);
    free(layout->array_index);
  }
  if (layout->associate_definition) {
    for (i = 0; i < layout->n_associates; i++) {
      if (layout->associate_definition[i].name)
        free(layout->associate_definition[i].name);
      if (layout->associate_definition[i].filename)
        free(layout->associate_definition[i].filename);
      if (layout->associate_definition[i].path)
        free(layout->associate_definition[i].path);
      if (layout->associate_definition[i].description)
        free(layout->associate_definition[i].description);
      if (layout->associate_definition[i].contents)
        free(layout->associate_definition[i].contents);
    }
    free(layout->associate_definition);
  }
  SDDS_ZeroMemory(&SDDS_dataset->original_layout, sizeof(SDDS_LAYOUT));
  layout = &SDDS_dataset->layout;
  if (layout->contents)
    free(layout->contents);
  if (layout->column_definition)
    free(layout->column_definition);
  if (layout->array_definition)
    free(layout->array_definition);
  if (layout->associate_definition)
    free(layout->associate_definition);
  if (layout->parameter_definition)
    free(layout->parameter_definition);
  if (layout->column_index)
    free(layout->column_index);
  if (layout->parameter_index)
    free(layout->parameter_index);
  if (layout->array_index)
    free(layout->array_index);
  SDDS_ZeroMemory(&SDDS_dataset->layout, sizeof(SDDS_LAYOUT));
  SDDS_ZeroMemory(SDDS_dataset, sizeof(SDDS_DATASET));
#if DEBUG
  fprintf(stderr, "done\n");
#endif
  return (1);
}

SDDS_TransferAllArrayDefinitions()

epicsShareFuncSDDS int32_t SDDS_TransferAllArrayDefinitions ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source, uint32_t mode )

extern

Transfers all array definitions from a source dataset to a target dataset.

This function defines all arrays in the target SDDS dataset to match the array definitions in the source SDDS dataset. Currently, only mode 0 is supported, which results in an error if any array already exists in the target dataset.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure representing the target dataset.
SDDS_source	Pointer to the SDDS_DATASET structure representing the source dataset.
mode	Flags that determine how to handle existing arrays. Valid value: 0: Error if an array already exists in the target dataset.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Note

Non-zero mode flags are not supported for array definitions.

Definition at line 506 of file SDDS_transfer.c.

                                                                                                              {
  SDDS_LAYOUT *source;
  int32_t i;
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_TransferAllArrayDefinitions"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_TransferAllArrayDefinitions"))
    return (0);
  if (mode) {
    /* haven't done this one yet */
    SDDS_SetError("Nonzero mode not supported for arrays (SDDS_TransferAllArrayDefinitions)");
    return 0;
  }
  source = &SDDS_source->layout;
  SDDS_DeferSavingLayout(SDDS_target, 1);
  for (i = 0; i < source->n_arrays; i++)
    if (SDDS_DefineArray(SDDS_target, source->array_definition[i].name, source->array_definition[i].symbol,
                         source->array_definition[i].units, source->array_definition[i].description,
                         source->array_definition[i].format_string, source->array_definition[i].type, source->array_definition[i].field_length, source->array_definition[i].dimensions, source->array_definition[i].group_name) < 0) {
      SDDS_SetError("Unable to define array (SDDS_TransferAllArrayDefinitions)");
      SDDS_DeferSavingLayout(SDDS_target, 0);
      return 0;
    }
  SDDS_DeferSavingLayout(SDDS_target, 0);
  return 1;
}

SDDS_TransferAllColumnDefinitions()

epicsShareFuncSDDS int32_t SDDS_TransferAllColumnDefinitions ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source, uint32_t mode )

extern

Transfers all column definitions from a source dataset to a target dataset.

This function defines all columns in the target SDDS dataset to match the column definitions in the source SDDS dataset. It handles existing columns based on the specified mode.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure representing the target dataset.
SDDS_source	Pointer to the SDDS_DATASET structure representing the source dataset.
mode	Flags that determine how to handle existing columns. Valid flags include: 0: Error if a column already exists in the target dataset. SDDS_TRANSFER_KEEPOLD: Retain existing columns in the target dataset and skip transferring conflicting columns. SDDS_TRANSFER_OVERWRITE: Overwrite existing columns in the target dataset with definitions from the source dataset.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 424 of file SDDS_transfer.c.

                                                                                                               {
  SDDS_LAYOUT *target, *source;
  int32_t i, index;
  char messBuffer[1024];
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_TransferAllColumnDefinitions"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_TransferAllColumnDefinitions"))
    return (0);
  if (mode & SDDS_TRANSFER_KEEPOLD && mode & SDDS_TRANSFER_OVERWRITE) {
    SDDS_SetError("Inconsistent mode flags (SDDS_TransferAllColumnDefinitions)");
    return 0;
  }
  target = &SDDS_target->layout;
  source = &SDDS_source->layout;
  SDDS_DeferSavingLayout(SDDS_target, 1);
  for (i = 0; i < source->n_columns; i++)
    if ((index = SDDS_GetColumnIndex(SDDS_target, source->column_definition[i].name)) >= 0) {
      /* already exists */
      if (mode & SDDS_TRANSFER_KEEPOLD)
        continue;
      if (!(mode & SDDS_TRANSFER_OVERWRITE)) {
        sprintf(messBuffer, "Unable to define column %s---already exists (SDDS_TransferAllColumnDefinitions)", source->column_definition[i].name);
        SDDS_SetError(messBuffer);
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
      if (source->column_definition[i].type != target->column_definition[index].type && SDDS_target->n_rows_allocated) {
        sprintf(messBuffer, "Unable to define column %s---type mismatch and table already allocated (SDDS_TransferAllColumnDefinitions)", source->column_definition[i].name);
        SDDS_SetError(messBuffer);
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
      if (!SDDS_ChangeColumnInformation(SDDS_target, "symbol",
                                        &source->column_definition[i].symbol,
                                        SDDS_BY_INDEX, index) ||
          !SDDS_ChangeColumnInformation(SDDS_target, "units",
                                        &source->column_definition[i].units,
                                        SDDS_BY_INDEX, index) ||
          !SDDS_ChangeColumnInformation(SDDS_target, "description",
                                        &source->column_definition[i].description,
                                        SDDS_BY_INDEX, index) ||
          !SDDS_ChangeColumnInformation(SDDS_target, "format_string",
                                        &source->column_definition[i].format_string,
                                        SDDS_BY_INDEX, index) ||
          !SDDS_ChangeColumnInformation(SDDS_target, "type", &source->column_definition[i].type, SDDS_BY_INDEX, index) || !SDDS_ChangeColumnInformation(SDDS_target, "field_length", &source->column_definition[i].field_length, SDDS_BY_INDEX, index)) {
        SDDS_SetError("Unable to define column---problem with overwrite (SDDS_TransferAllColumnDefinitions)");
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
      target->column_definition[index].definition_mode = source->column_definition[index].definition_mode;
      if (target->column_definition[index].type == SDDS_STRING)
        target->column_definition[index].memory_number = SDDS_CreateRpnMemory(source->column_definition[i].name, 1);
      else
        target->column_definition[index].memory_number = SDDS_CreateRpnMemory(source->column_definition[i].name, 0);
    } else {
      if (SDDS_DefineColumn(SDDS_target, source->column_definition[i].name, source->column_definition[i].symbol,
                            source->column_definition[i].units, source->column_definition[i].description, source->column_definition[i].format_string, source->column_definition[i].type, source->column_definition[i].field_length) < 0) {
        SDDS_SetError("Unable to define column (SDDS_TransferAllColumnDefinitions)");
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
    }
  SDDS_DeferSavingLayout(SDDS_target, 0);
  return 1;
}

SDDS_TransferAllParameterDefinitions()

epicsShareFuncSDDS int32_t SDDS_TransferAllParameterDefinitions ( SDDS_DATASET * SDDS_target, SDDS_DATASET * SDDS_source, uint32_t mode )

extern

Transfers all parameter definitions from a source dataset to a target dataset.

This function defines all parameters in the target SDDS dataset to match the parameter definitions in the source SDDS dataset. It handles existing parameters based on the specified mode.

Parameters

SDDS_target	Pointer to the SDDS_DATASET structure representing the target dataset.
SDDS_source	Pointer to the SDDS_DATASET structure representing the source dataset.
mode	Flags that determine how to handle existing parameters. Valid flags include: 0: Error if a parameter already exists in the target dataset. SDDS_TRANSFER_KEEPOLD: Retain existing parameters in the target dataset and skip transferring conflicting parameters. SDDS_TRANSFER_OVERWRITE: Overwrite existing parameters in the target dataset with definitions from the source dataset.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 343 of file SDDS_transfer.c.

                                                                                                                  {
  SDDS_LAYOUT *target, *source;
  int32_t i, index;
  char messBuffer[1024];
 
  if (!SDDS_CheckDataset(SDDS_target, "SDDS_TransferAllParameterDefinitions"))
    return (0);
  if (!SDDS_CheckDataset(SDDS_source, "SDDS_TransferAllParameterDefinitions"))
    return (0);
  if (mode & SDDS_TRANSFER_KEEPOLD && mode & SDDS_TRANSFER_OVERWRITE) {
    SDDS_SetError("Inconsistent mode flags (SDDS_TransferAllParameterDefinitions)");
    return 0;
  }
  target = &SDDS_target->layout;
  source = &SDDS_source->layout;
  SDDS_DeferSavingLayout(SDDS_target, 1);
  for (i = 0; i < source->n_parameters; i++) {
    if ((index = SDDS_GetParameterIndex(SDDS_target, source->parameter_definition[i].name)) >= 0) {
      /* already exists */
      if (mode & SDDS_TRANSFER_KEEPOLD)
        continue;
      if (!(mode & SDDS_TRANSFER_OVERWRITE)) {
        sprintf(messBuffer, "Unable to define parameter %s---already exists (SDDS_TransferAllParameterDefinitions)", source->parameter_definition[i].name);
        SDDS_SetError(messBuffer);
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
      if (!SDDS_ChangeParameterInformation(SDDS_target, "symbol",
                                           &source->parameter_definition[i].symbol,
                                           SDDS_BY_INDEX, index) ||
          !SDDS_ChangeParameterInformation(SDDS_target, "units",
                                           &source->parameter_definition[i].units,
                                           SDDS_BY_INDEX, index) ||
          !SDDS_ChangeParameterInformation(SDDS_target, "description",
                                           &source->parameter_definition[i].description,
                                           SDDS_BY_INDEX, index) ||
          !SDDS_ChangeParameterInformation(SDDS_target, "format_string",
                                           &source->parameter_definition[i].format_string,
                                           SDDS_BY_INDEX, index) ||
          !SDDS_ChangeParameterInformation(SDDS_target, "type",
                                           &source->parameter_definition[i].type, SDDS_BY_INDEX, index) ||
          (source->parameter_definition[i].fixed_value != NULL && !SDDS_ChangeParameterInformation(SDDS_target, "fixed_value", &source->parameter_definition[i].fixed_value, SDDS_BY_INDEX, index))) {
        SDDS_SetError("Unable to define parameter---problem with overwrite (SDDS_TransferAllParameterDefinitions)");
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
      if (source->parameter_definition[i].fixed_value == NULL)
        target->parameter_definition[index].fixed_value = NULL;
      target->parameter_definition[index].definition_mode = source->parameter_definition[index].definition_mode;
      if (target->parameter_definition[index].type == SDDS_STRING)
        target->parameter_definition[index].memory_number = SDDS_CreateRpnMemory(source->parameter_definition[i].name, 1);
      else
        target->parameter_definition[index].memory_number = SDDS_CreateRpnMemory(source->parameter_definition[i].name, 0);
    } else {
      if (SDDS_DefineParameter(SDDS_target, source->parameter_definition[i].name,
                               source->parameter_definition[i].symbol, source->parameter_definition[i].units, source->parameter_definition[i].description, source->parameter_definition[i].format_string, source->parameter_definition[i].type, source->parameter_definition[i].fixed_value) < 0) {
        SDDS_SetError("Unable to define parameter (SDDS_TransferAllParameterDefinitions)");
        SDDS_DeferSavingLayout(SDDS_target, 0);
        return 0;
      }
    }
  }
  SDDS_DeferSavingLayout(SDDS_target, 0);
  return 1;
}

SDDS_TransferArrayDefinition()

epicsShareFuncSDDS int32_t SDDS_TransferArrayDefinition ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Transfers an array definition from a source dataset to a target dataset.

This function defines an array in the target SDDS dataset to match the definition of an array in the source SDDS dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the array in the source dataset to be transferred.
newName	The name of the array in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 111 of file SDDS_transfer.c.

                                                                                                            {
  ARRAY_DEFINITION *ardef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to transfer array definition--NULL or blank name passed (SDDS_TransferArrayDefinition)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(ardef = SDDS_GetArrayDefinition(source, name))) {
    SDDS_SetError("Unable to transfer array definition--unknown array named (SDDS_TransferArrayDefinition)");
    return 0;
  }
  if (SDDS_GetArrayIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to transfer array definition--array already present (SDDS_TransferArrayDefinition)");
    return 0;
  }
  if (SDDS_DefineArray(target, newName, ardef->symbol, ardef->units, ardef->description, ardef->format_string, ardef->type, ardef->field_length, ardef->dimensions, ardef->group_name) < 0) {
    SDDS_FreeArrayDefinition(ardef);
    SDDS_SetError("Unable to transfer array definition--call to define array failed (SDDS_TransferArrayDefinition)");
    return 0;
  }
  SDDS_FreeArrayDefinition(ardef);
  return 1;
}

SDDS_TransferAssociateDefinition()

epicsShareFuncSDDS int32_t SDDS_TransferAssociateDefinition ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Transfers an associate definition from a source dataset to a target dataset.

This function defines an associate in the target SDDS dataset to match the definition of an associate in the source SDDS dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the associate in the source dataset to be transferred.
newName	The name of the associate in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 149 of file SDDS_transfer.c.

                                                                                                                {
  ASSOCIATE_DEFINITION *asdef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to transfer associate definition--NULL or blank name passed (SDDS_TransferAssociateDefinition)");
    return 0;
  }
  if (!newName)
    newName = name;
  if ((asdef = SDDS_GetAssociateDefinition(target, name))) {
    SDDS_FreeAssociateDefinition(asdef);
    SDDS_SetError("Unable to transfer associate definition--associate already present (SDDS_TransferAssociateDefinition)");
    return 0;
  }
  if (!(asdef = SDDS_GetAssociateDefinition(source, newName))) {
    SDDS_SetError("Unable to transfer associate definition--unknown associate named (SDDS_TransferAssociateDefinition)");
    return 0;
  }
  if (SDDS_DefineAssociate(target, newName, asdef->filename, asdef->path, asdef->description, asdef->contents, asdef->sdds) < 0) {
    SDDS_FreeAssociateDefinition(asdef);
    SDDS_SetError("Unable to transfer associate definition--call to define associate failed (SDDS_TransferAssociateDefinition)");
    return 0;
  }
  SDDS_FreeAssociateDefinition(asdef);
  return 1;
}

SDDS_TransferColumnDefinition()

epicsShareFuncSDDS int32_t SDDS_TransferColumnDefinition ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Transfers a column definition from a source dataset to a target dataset.

This function defines a column in the target SDDS dataset to match the definition of a column in the source SDDS dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the column in the source dataset to be transferred.
newName	The name of the column in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 35 of file SDDS_transfer.c.

                                                                                                             {
  COLUMN_DEFINITION *coldef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to transfer column definition--NULL or blank name passed (SDDS_TransferColumnDefinition)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(coldef = SDDS_GetColumnDefinition(source, name))) {
    SDDS_SetError("Unable to transfer column definition--unknown column named (SDDS_TransferColumnDefinition)");
    return 0;
  }
  if (SDDS_GetColumnIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to transfer column definition--column already present (SDDS_TransferColumnDefinition)");
    return 0;
  }
  if (SDDS_DefineColumn(target, newName, coldef->symbol, coldef->units, coldef->description, coldef->format_string, coldef->type, coldef->field_length) < 0) {
    SDDS_FreeColumnDefinition(coldef);
    SDDS_SetError("Unable to transfer column definition--call to define column failed (SDDS_TransferColumnDefinition)");
    return 0;
  }
  SDDS_FreeColumnDefinition(coldef);
  return 1;
}

SDDS_TransferParameterDefinition()

epicsShareFuncSDDS int32_t SDDS_TransferParameterDefinition ( SDDS_DATASET * target, SDDS_DATASET * source, char * name, char * newName )

extern

Transfers a parameter definition from a source dataset to a target dataset.

This function defines a parameter in the target SDDS dataset to match the definition of a parameter in the source SDDS dataset.

Parameters

target	Pointer to the SDDS_DATASET structure representing the target dataset.
source	Pointer to the SDDS_DATASET structure representing the source dataset.
name	The name of the parameter in the source dataset to be transferred.
newName	The name of the parameter in the target dataset. If NULL, the original name is used.

Returns

1 on success; 0 on failure. On failure, an error message is recorded.

Definition at line 73 of file SDDS_transfer.c.

                                                                                                                {
  PARAMETER_DEFINITION *pardef;
 
  if (!name || SDDS_StringIsBlank(name)) {
    SDDS_SetError("Unable to transfer parameter definition--NULL or blank name passed (SDDS_TransferParameterDefinition)");
    return 0;
  }
  if (!newName)
    newName = name;
  if (!(pardef = SDDS_GetParameterDefinition(source, name))) {
    SDDS_SetError("Unable to transfer parameter definition--unknown parameter named (SDDS_TransferParameterDefinition)");
    return 0;
  }
  if (SDDS_GetParameterIndex(target, newName) >= 0) {
    SDDS_SetError("Unable to transfer parameter definition--parameter already present (SDDS_TransferParameterDefinition)");
    return 0;
  }
  if (SDDS_DefineParameter(target, newName, pardef->symbol, pardef->units, pardef->description, pardef->format_string, pardef->type, NULL) < 0) {
    SDDS_FreeParameterDefinition(pardef);
    SDDS_SetError("Unable to transfer parameter definition--call to define parameter failed (SDDS_TransferParameterDefinition)");
    return 0;
  }
  SDDS_FreeParameterDefinition(pardef);
  return 1;
}

SDDS_UnescapeQuotes()

epicsShareFuncSDDS void SDDS_UnescapeQuotes ( char * s, char quote_char )

extern

Removes escape characters from quote characters within a string.

This function scans the input string s and removes backslashes (\) that precede the specified quote_char, effectively unescaping the quotes. This is useful for processing strings that have been prepared with escaped quotes.

Parameters

[in,out]	s	Pointer to the string in which quotes will be unescaped. The string will be modified in place.
[in]	quote_char	The quote character to unescape (e.g., ").

Note

The function modifies the string s by shifting characters to remove the escape backslashes. It assumes that s is properly null-terminated.

See also

SDDS_EscapeQuotes

Definition at line 1998 of file SDDS_utils.c.

                                                   {
  char *ptr;
  ptr = s;
  while (*ptr) {
    if (*ptr == quote_char && ptr != s && *(ptr - 1) == '\\')
      strcpy(ptr - 1, ptr);
    else
      ptr++;
  }
}

SDDS_UpdatePage()

epicsShareFuncSDDS int32_t SDDS_UpdatePage ( SDDS_DATASET * SDDS_dataset, uint32_t mode )

extern

Updates the current page of the SDDS dataset.

This function finalizes and writes the current page of the SDDS dataset based on the specified mode. The mode can be either FLUSH_TABLE, indicating that the current page is complete and should be written to disk, or 0 for other update operations. Depending on the data mode (ASCII or Binary), the function delegates the update process to the appropriate handler.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset.
[in]	mode	The update mode, which can be: FLUSH_TABLE: Indicates that the current page is complete and should be written to disk. 0: Represents a standard update without flushing the table.

Returns

• 1 on successful update of the current page.
• 0 if an error occurred during the update process. An error message is set internally in this case.

Precondition

• The dataset must be initialized and configured for output.
• A page must have been started before calling this function.

Postcondition

• The current page is updated and, if specified, written to the output file.
• The dataset state is synchronized with the file to ensure data integrity.

Note

• The function supports parallel I/O modes if enabled.
• The FLUSH_TABLE mode ensures that all buffered data is written to the disk, which can be useful for data integrity.

Warning

• Attempting to update a page without starting one will result in an error.
• Concurrent access to the dataset while updating pages may lead to undefined behavior.

Definition at line 1292 of file SDDS_output.c.

                                                                   {
  int32_t result;
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_UpdatePage"))
    return 0;
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't write page--file is disconnected (SDDS_UpdatePage)");
    return 0;
  }
  if (SDDS_dataset->page_started == 0) {
    SDDS_SetError("Can't update page--no page started (SDDS_UpdatePage)");
    return 0;
  }
  if (SDDS_dataset->layout.data_mode.mode == SDDS_ASCII)
    result = SDDS_UpdateAsciiPage(SDDS_dataset, mode);
  else if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY)
    result = SDDS_UpdateBinaryPage(SDDS_dataset, mode);
  else {
    SDDS_SetError("Unable to update page--unknown data mode (SDDS_UpdatePage)");
    return 0;
  }
  if (result == 1)
    if (SDDS_SyncDataSet(SDDS_dataset) != 0)
      return 0;
  return (result);
}

SDDS_UpdateRowCount()

epicsShareFuncSDDS int32_t SDDS_UpdateRowCount ( SDDS_DATASET * SDDS_dataset )

extern

Updates the row count in the SDDS file for fixed row count mode.

Parameters

SDDS_dataset

The SDDS dataset to update.

Returns

1 on success, 0 on error.

Definition at line 1727 of file SDDS_input.c.

                                                        {
  FILE *fp;
  SDDS_FILEBUFFER *fBuffer;
  int64_t offset, rows;
  int32_t rows32;
  char *outputEndianess = NULL;
 
  if ((SDDS_dataset->layout.gzipFile) || (SDDS_dataset->layout.lzmaFile))
    return (1);
  if (!(fp = SDDS_dataset->layout.fp)) {
    SDDS_SetError("Unable to update page--file pointer is NULL (SDDS_UpdateRowCount)");
    return (0);
  }
#if DEBUG
  fprintf(stderr, "Updating rowcount in file %s with pointer %p\n", SDDS_dataset->layout.filename ? SDDS_dataset->layout.filename : "NULL", fp);
#endif
  fBuffer = &SDDS_dataset->fBuffer;
  if (!SDDS_FlushBuffer(fp, fBuffer)) {
    SDDS_SetError("Unable to write page--buffer flushing problem (SDDS_UpdateRowCount)");
    return (0);
  }
  offset = ftell(fp);
  if (SDDS_fseek(fp, SDDS_dataset->rowcount_offset, 0) == -1) {
    SDDS_SetError("Unable to update page--failure doing fseek (SDDS_UpdateRowCount)");
    return (0);
  }
  rows = SDDS_CountRowsOfInterest(SDDS_dataset) + SDDS_dataset->first_row_in_mem;
  if (SDDS_dataset->layout.data_mode.mode == SDDS_ASCII) {
    fprintf(fp, "%20" PRId64 "\n", rows);
  } else {
 
    if (rows > INT32_MAX) {
      // Don't go over this limit because it has a different format
      SDDS_SetError("Unable to update page--failure writing number of rows (SDDS_UpdateRowCount)");
      return (0);
    }
    rows32 = (int32_t)rows;
    if ((outputEndianess = getenv("SDDS_OUTPUT_ENDIANESS"))) {
      if (((strncmp(outputEndianess, "big", 3) == 0) && (SDDS_IsBigEndianMachine() == 0)) || ((strncmp(outputEndianess, "little", 6) == 0) && (SDDS_IsBigEndianMachine() == 1)))
        SDDS_SwapLong(&rows32);
    }
    if (fwrite(&rows32, sizeof(rows32), 1, fp) != 1) {
      SDDS_SetError("Unable to update page--failure writing number of rows (SDDS_UpdateRowCount)");
      return (0);
    }
  }
  if (SDDS_fseek(fp, offset, 0) == -1) {
    SDDS_SetError("Unable to update page--failure doing fseek to end of page (SDDS_UpdateRowCount)");
    return (0);
  }
  return (1);
}

SDDS_VerifyArrayExists()

epicsShareFuncSDDS int32_t SDDS_VerifyArrayExists ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Verifies the existence of an array in the SDDS dataset based on specified criteria.

This function searches for an array within the SDDS dataset that matches the given criteria defined by the mode. It returns the index of the first matching array or -1 if no match is found.

The function supports the following modes:

• FIND_SPECIFIED_TYPE:
  • Parameters: int32_t type, char *name
  • Description: Finds the first array with the specified type.
• FIND_ANY_TYPE:
  • Parameters: char *name
  • Description: Finds the first array with any type.
• FIND_NUMERIC_TYPE:
  • Parameters: char *name
  • Description: Finds the first array with a numeric type.
• FIND_FLOATING_TYPE:
  • Parameters: char *name
  • Description: Finds the first array with a floating type.
• FIND_INTEGER_TYPE:
  • Parameters: char *name
  • Description: Finds the first array with an integer type.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to be searched.
[in]	mode	Specifies the mode for matching arrays. Valid modes are: FIND_SPECIFIED_TYPE FIND_ANY_TYPE FIND_NUMERIC_TYPE FIND_FLOATING_TYPE FIND_INTEGER_TYPE
[in]	...	Variable arguments depending on mode: FIND_SPECIFIED_TYPE: int32_t type, followed by char *name Other Modes: char *name

Returns

• Returns the index (int32_t) of the first matched array.
• Returns -1 if no matching array is found.

Note

• The caller must ensure that the variable arguments match the expected parameters for the specified mode.

Warning

• Passing incorrect types or mismatched arguments may lead to undefined behavior.

See also

SDDS_GetArrayIndex, SDDS_CheckArray, SDDS_MatchArrays

Definition at line 5435 of file SDDS_utils.c.

                                                                              {
  int32_t index, type, thisType;
  va_list argptr;
  char *name;
 
  va_start(argptr, mode);
  type = 0;
 
  if (mode == FIND_SPECIFIED_TYPE)
    type = va_arg(argptr, int32_t);
  name = va_arg(argptr, char *);
  if ((index = SDDS_GetArrayIndex(SDDS_dataset, name)) >= 0) {
    thisType = SDDS_GetArrayType(SDDS_dataset, index);
    if (mode == FIND_ANY_TYPE || (mode == FIND_SPECIFIED_TYPE && thisType == type) || (mode == FIND_NUMERIC_TYPE && SDDS_NUMERIC_TYPE(thisType)) || (mode == FIND_FLOATING_TYPE && SDDS_FLOATING_TYPE(thisType)) || (mode == FIND_INTEGER_TYPE && SDDS_INTEGER_TYPE(thisType))) {
      va_end(argptr);
      return (index);
    }
  }
  va_end(argptr);
  return (-1);
}

SDDS_VerifyColumnExists()

epicsShareFuncSDDS int32_t SDDS_VerifyColumnExists ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Verifies the existence of a column in the SDDS dataset based on specified criteria.

This function searches for a column within the SDDS dataset that matches the given criteria defined by the mode. It returns the index of the first matching column or -1 if no match is found.

The function supports the following modes:

• FIND_SPECIFIED_TYPE:
  • Parameters: int32_t type, char *name
  • Description: Finds the first column with the specified type.
• FIND_ANY_TYPE:
  • Parameters: char *name
  • Description: Finds the first column with any type.
• FIND_NUMERIC_TYPE:
  • Parameters: char *name
  • Description: Finds the first column with a numeric type.
• FIND_FLOATING_TYPE:
  • Parameters: char *name
  • Description: Finds the first column with a floating type.
• FIND_INTEGER_TYPE:
  • Parameters: char *name
  • Description: Finds the first column with an integer type.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to be searched.
[in]	mode	Specifies the mode for matching columns. Valid modes are: FIND_SPECIFIED_TYPE FIND_ANY_TYPE FIND_NUMERIC_TYPE FIND_FLOATING_TYPE FIND_INTEGER_TYPE
[in]	...	Variable arguments depending on mode: FIND_SPECIFIED_TYPE: int32_t type, followed by char *name Other Modes: char *name

Returns

• Returns the index (int32_t) of the first matched column.
• Returns -1 if no matching column is found.

Note

• The caller must ensure that the variable arguments match the expected parameters for the specified mode.

Warning

• Passing incorrect types or mismatched arguments may lead to undefined behavior.

See also

SDDS_GetColumnIndex, SDDS_CheckColumn, SDDS_MatchColumns

Definition at line 5511 of file SDDS_utils.c.

                                                                               {
  int32_t index;
  int32_t type, thisType;
  va_list argptr;
  char *name;
 
  va_start(argptr, mode);
  type = 0;
 
  if (mode == FIND_SPECIFIED_TYPE)
    type = va_arg(argptr, int32_t);
  name = va_arg(argptr, char *);
  if ((index = SDDS_GetColumnIndex(SDDS_dataset, name)) >= 0) {
    thisType = SDDS_GetColumnType(SDDS_dataset, index);
    if (mode == FIND_ANY_TYPE || (mode == FIND_SPECIFIED_TYPE && thisType == type) || (mode == FIND_NUMERIC_TYPE && SDDS_NUMERIC_TYPE(thisType)) || (mode == FIND_FLOATING_TYPE && SDDS_FLOATING_TYPE(thisType)) || (mode == FIND_INTEGER_TYPE && SDDS_INTEGER_TYPE(thisType))) {
      va_end(argptr);
      return (index);
    }
  }
  va_end(argptr);
  return (-1);
}

SDDS_VerifyParameterExists()

epicsShareFuncSDDS int32_t SDDS_VerifyParameterExists ( SDDS_DATASET * SDDS_dataset, int32_t mode, ... )

extern

Verifies the existence of a parameter in the SDDS dataset based on specified criteria.

This function searches for a parameter within the SDDS dataset that matches the given criteria defined by the mode. It returns the index of the first matching parameter or -1 if no match is found.

The function supports the following modes:

• FIND_SPECIFIED_TYPE:
  • Parameters: int32_t type, char *name
  • Description: Finds the first parameter with the specified type.
• FIND_ANY_TYPE:
  • Parameters: char *name
  • Description: Finds the first parameter with any type.
• FIND_NUMERIC_TYPE:
  • Parameters: char *name
  • Description: Finds the first parameter with a numeric type.
• FIND_FLOATING_TYPE:
  • Parameters: char *name
  • Description: Finds the first parameter with a floating type.
• FIND_INTEGER_TYPE:
  • Parameters: char *name
  • Description: Finds the first parameter with an integer type.

Parameters

[in]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to be searched.
[in]	mode	Specifies the mode for matching parameters. Valid modes are: FIND_SPECIFIED_TYPE FIND_ANY_TYPE FIND_NUMERIC_TYPE FIND_FLOATING_TYPE FIND_INTEGER_TYPE
[in]	...	Variable arguments depending on mode: FIND_SPECIFIED_TYPE: int32_t type, followed by char *name Other Modes: char *name

Returns

• Returns the index (int32_t) of the first matched parameter.
• Returns -1 if no matching parameter is found.

Note

• The caller must ensure that the variable arguments match the expected parameters for the specified mode.

Warning

• Passing incorrect types or mismatched arguments may lead to undefined behavior.

See also

SDDS_GetParameterIndex, SDDS_CheckParameter, SDDS_MatchParameters

Definition at line 5588 of file SDDS_utils.c.

                                                                                  {
  int32_t index, type, thisType;
  va_list argptr;
  char *name;
 
  va_start(argptr, mode);
  type = 0;
 
  if (mode == FIND_SPECIFIED_TYPE)
    type = va_arg(argptr, int32_t);
  name = va_arg(argptr, char *);
  if ((index = SDDS_GetParameterIndex(SDDS_dataset, name)) >= 0) {
    thisType = SDDS_GetParameterType(SDDS_dataset, index);
    if (mode == FIND_ANY_TYPE || (mode == FIND_SPECIFIED_TYPE && thisType == type) || (mode == FIND_NUMERIC_TYPE && SDDS_NUMERIC_TYPE(thisType)) || (mode == FIND_FLOATING_TYPE && SDDS_FLOATING_TYPE(thisType)) || (mode == FIND_INTEGER_TYPE && SDDS_INTEGER_TYPE(thisType))) {
      va_end(argptr);
      return (index);
    }
  }
  va_end(argptr);
  return (-1);
}

SDDS_VerifyPrintfFormat()

epicsShareFuncSDDS int32_t SDDS_VerifyPrintfFormat ( const char * string, int32_t type )

extern

Verifies that a printf format string is compatible with a specified data type.

This function checks whether the provided printf format string is appropriate for the given SDDS data type. It ensures that the format specifier matches the type, preventing potential formatting errors during data output.

Parameters

[in]	string	The printf format string to be verified.
[in]	type	The data type against which the format string is verified. Must be one of the SDDS type constants: SDDS_LONGDOUBLE SDDS_DOUBLE SDDS_FLOAT SDDS_LONG SDDS_LONG64 SDDS_ULONG SDDS_ULONG64 SDDS_SHORT SDDS_USHORT SDDS_STRING SDDS_CHARACTER

Returns

Returns 1 if the format string is valid for the specified type; otherwise, returns 0 and records an error message.

Note

This function does not modify the format string; it only validates its compatibility with the given type.

See also

SDDS_SetError

Definition at line 816 of file SDDS_utils.c.

                                                                  {
  char *percent, *s;
  int32_t len, tmp;
 
  s = (char *)string;
  do {
    if ((percent = strchr(s, '%'))) {
      if (*(percent + 1) != '%')
        break;
      s = percent + 1;
    }
  } while (percent);
  if (!percent || !*++percent)
    return (0);
 
  s = percent;
 
  switch (type) {
  case SDDS_LONGDOUBLE:
  case SDDS_DOUBLE:
  case SDDS_FLOAT:
    if ((len = strcspn(s, "fegEG")) == strlen(s))
      return (0);
    if (len == 0)
      return (1);
    if ((tmp = strspn(s, "-+.0123456789 ")) < len)
      return (0);
    break;
  case SDDS_LONG:
  case SDDS_LONG64:
    if ((len = strcspn(s, "d")) == strlen(s))
      return (0);
    /*    if (*(s+len-1)!='l')
            return(0); */
    if (--len == 0)
      return (1);
    if ((tmp = strspn(s, "-+.0123456789 ")) < len)
      return (0);
    break;
  case SDDS_ULONG:
  case SDDS_ULONG64:
    if ((len = strcspn(s, "u")) == strlen(s))
      return (0);
    /*    if (*(s+len-1)!='l')
            return(0); */
    if (--len == 0)
      return (1);
    if ((tmp = strspn(s, "-+.0123456789 ")) < len)
      return (0);
    break;
  case SDDS_SHORT:
    if ((len = strcspn(s, "d")) == strlen(s))
      return (0);
    if (*(s + len - 1) != 'h')
      return (0);
    if (--len == 0)
      return (1);
    if ((tmp = strspn(s, "-+.0123456789 ")) < len)
      return (0);
    break;
  case SDDS_USHORT:
    if ((len = strcspn(s, "u")) == strlen(s))
      return (0);
    if (*(s + len - 1) != 'h')
      return (0);
    if (--len == 0)
      return (1);
    if ((tmp = strspn(s, "-+.0123456789 ")) < len)
      return (0);
    break;
  case SDDS_STRING:
    if ((len = strcspn(s, "s")) == strlen(s))
      return (0);
    if (len == 0)
      return (1);
    if ((tmp = strspn(s, "-0123456789")) < len)
      return (0);
    break;
  case SDDS_CHARACTER:
    if ((len = strcspn(s, "c")) == strlen(s))
      return (0);
    if (len != 0)
      return (0);
    break;
  default:
    return (0);
  }
  /* no errors found--its probably okay */
  return (1);
}

SDDS_Warning()

epicsShareFuncSDDS void SDDS_Warning ( char * message )

extern

Prints a warning message to stderr.

This function outputs a warning message to the specified FILE stream, typically stderr. If a program name has been registered using SDDS_RegisterProgramName, it is included in the warning message.

Parameters

[in]

message

The warning message to be printed. If NULL, a default message "?" is used.

Note

This function does not record the warning as an error; it only prints the message.

See also

SDDS_RegisterProgramName

Definition at line 402 of file SDDS_utils.c.

                                 {
  char *programName = SDDS_GetRegisteredProgramNameCopy();
  if (programName)
    fprintf(stderr, "Warning (%s): %s\n", programName, message ? message : "?");
  else
    fprintf(stderr, "Warning: %s\n", message ? message : "?");
  free(programName);
}

SDDS_WriteBinaryString()

epicsShareFuncSDDS int32_t SDDS_WriteBinaryString ( char * string, FILE * fp, SDDS_FILEBUFFER * fBuffer )

extern

Writes a binary string to a file with buffering.

This function writes a binary string to the specified file by first writing the length of the string followed by the string's content to ensure proper binary formatting. If the input string is NULL, an empty string is written instead. The writing operation utilizes a buffered approach to enhance performance.

Parameters

[in]	string	The null-terminated string to be written. If NULL, an empty string is written.
[in]	fp	The file pointer to write to. Must be an open file in binary write mode.
[in,out]	fBuffer	Pointer to the file buffer used for buffered writing operations.

Returns

int32_t Returns 1 on success, 0 on failure.

Return values

1	Operation was successful.
0	An error occurred during writing.

Definition at line 2642 of file SDDS_binary.c.

                                                                                 {
  int32_t length;
  static const char dummy_string[] = "";
  if (!string)
    string = (char *)dummy_string;
  length = strlen(string);
  if (!SDDS_BufferedWrite(&length, sizeof(length), fp, fBuffer)) {
    SDDS_SetError("Unable to write string--error writing length");
    return (0);
  }
  if (length && !SDDS_BufferedWrite(string, sizeof(*string) * length, fp, fBuffer)) {
    SDDS_SetError("Unable to write string--error writing contents");
    return (0);
  }
  return (1);
}

SDDS_WriteLayout()

epicsShareFuncSDDS int32_t SDDS_WriteLayout ( SDDS_DATASET * SDDS_dataset )

extern

Writes the SDDS layout header to the output file.

This function serializes and writes the layout information of the SDDS dataset to the output file. The layout defines the structure of the data tables, including parameters, arrays, columns, and associates. The function handles different file types, including standard, gzip-compressed, and LZMA-compressed files, and ensures that the layout is written in the correct byte order and format based on the dataset's configuration.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure whose layout is to be written.

Returns

• 1 on successful writing of the layout.
• 0 if an error occurred during the writing process. An internal error message is set in this case.

Precondition

• The dataset must be initialized and configured for output.
• The layout must have been saved internally using SDDS_SaveLayout before calling this function.
• The dataset must not be disconnected from the output file.
• The layout must not have been previously written to the file.

Postcondition

• The layout header is written to the output file in the appropriate format.
• The dataset's internal state is updated to reflect that the layout has been written.

Note

• The function automatically determines the layout version based on the data types used in parameters, arrays, and columns.
• Environment variable SDDS_OUTPUT_ENDIANESS can influence the byte order declared in the layout.
• The function handles both binary and ASCII modes, adjusting the layout accordingly.

Warning

• Attempting to write the layout after it has already been written will result in an error.
• The function does not support writing layouts to disconnected files.
• Ensure that the output file is properly opened and writable before calling this function.

Definition at line 900 of file SDDS_output.c.

                                                     {
  SDDS_LAYOUT *layout;
#if defined(zLib)
  gzFile gzfp;
#endif
  FILE *fp;
  struct lzmafile *lzmafp;
  int64_t i;
  char *outputEndianess = NULL;
 
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io)
    return SDDS_MPI_WriteLayout(SDDS_dataset);
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_WriteLayout"))
    return 0;
 
  if (!SDDS_SaveLayout(SDDS_dataset))
    return 0;
 
  layout = &SDDS_dataset->layout;
 
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't write layout--file is disconnected (SDDS_WriteLayout)");
    return 0;
  }
 
  if (layout->layout_written) {
    SDDS_SetError("Can't write layout--already written to file (SDDS_WriteLayout)");
    return 0;
  }
 
  if ((outputEndianess = getenv("SDDS_OUTPUT_ENDIANESS"))) {
    if (strncmp(outputEndianess, "big", 3) == 0)
      layout->byteOrderDeclared = SDDS_BIGENDIAN;
    else if (strncmp(outputEndianess, "little", 6) == 0)
      layout->byteOrderDeclared = SDDS_LITTLEENDIAN;
  }
 
  if (!layout->byteOrderDeclared)
    layout->byteOrderDeclared = SDDS_IsBigEndianMachine() ? SDDS_BIGENDIAN : SDDS_LITTLEENDIAN;
 
  layout->version = 1;
  for (i = 0; i < layout->n_parameters; i++) {
    if ((layout->parameter_definition[i].type == SDDS_ULONG) || (layout->parameter_definition[i].type == SDDS_USHORT)) {
      layout->version = 2;
      break;
    }
  }
  for (i = 0; i < layout->n_arrays; i++) {
    if ((layout->array_definition[i].type == SDDS_ULONG) || (layout->array_definition[i].type == SDDS_USHORT)) {
      layout->version = 2;
      break;
    }
  }
  for (i = 0; i < layout->n_columns; i++) {
    if ((layout->column_definition[i].type == SDDS_ULONG) || (layout->column_definition[i].type == SDDS_USHORT)) {
      layout->version = 2;
      break;
    }
  }
  if ((layout->data_mode.column_major) && (layout->data_mode.mode == SDDS_BINARY)) {
    layout->version = 3;
  }
  for (i = 0; i < layout->n_parameters; i++) {
    if (layout->parameter_definition[i].type == SDDS_LONGDOUBLE) {
      layout->version = 4;
      break;
    }
  }
  for (i = 0; i < layout->n_arrays; i++) {
    if (layout->array_definition[i].type == SDDS_LONGDOUBLE) {
      layout->version = 4;
      break;
    }
  }
  for (i = 0; i < layout->n_columns; i++) {
    if (layout->column_definition[i].type == SDDS_LONGDOUBLE) {
      layout->version = 4;
      break;
    }
  }
  if ((LDBL_DIG != 18) && (layout->version == 4)) {
    if (getenv("SDDS_LONGDOUBLE_64BITS") == NULL) {
      SDDS_SetError("Error: Operating system does not support 80bit float variables used by SDDS_LONGDOUBLE (SDDS_WriteLayout)\nSet SDDS_LONGDOUBLE_64BITS environment variable to read old files that used 64bit float variables for SDDS_LONGDOUBLE");
      return 0;
    }
  }
  for (i = 0; i < layout->n_parameters; i++) {
    if ((layout->parameter_definition[i].type == SDDS_ULONG64) || (layout->parameter_definition[i].type == SDDS_LONG64)) {
      layout->version = 5;
      break;
    }
  }
  for (i = 0; i < layout->n_arrays; i++) {
    if ((layout->array_definition[i].type == SDDS_ULONG64) || (layout->array_definition[i].type == SDDS_LONG64)) {
      layout->version = 5;
      break;
    }
  }
  for (i = 0; i < layout->n_columns; i++) {
    if ((layout->column_definition[i].type == SDDS_ULONG64) || (layout->column_definition[i].type == SDDS_LONG64)) {
      layout->version = 5;
      break;
    }
  }
 
  // force layout version 5 because the row and column indexes are now 64bit long integers
  // layout->version = 5;
 
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!(gzfp = layout->gzfp)) {
      SDDS_SetError("Can't write SDDS layout--file pointer is NULL (SDDS_WriteLayout)");
      return 0;
    }
 
    /* write out the layout data */
    if (!SDDS_GZipWriteVersion(layout->version, gzfp)) {
      SDDS_SetError("Can't write SDDS layout--error writing version (SDDS_WriteLayout)");
      return 0;
    }
    if (layout->version < 3) {
      if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY) {
        if (layout->byteOrderDeclared == SDDS_BIGENDIAN)
          gzprintf(gzfp, "!# big-endian\n");
        else
          gzprintf(gzfp, "!# little-endian\n");
      }
      if (SDDS_dataset->layout.data_mode.fixed_row_count) {
        gzprintf(gzfp, "!# fixed-rowcount\n");
      }
    }
    if (!SDDS_GZipWriteDescription(layout->description, layout->contents, gzfp)) {
      SDDS_SetError("Can't write SDDS layout--error writing description (SDDS_WriteLayout)");
      return 0;
    }
 
    for (i = 0; i < layout->n_parameters; i++)
      if (!SDDS_GZipWriteParameterDefinition(layout->parameter_definition + i, gzfp)) {
        SDDS_SetError("Unable to write layout--error writing parameter definition (SDDS_WriteLayout)");
        return 0;
      }
 
    for (i = 0; i < layout->n_arrays; i++)
      if (!SDDS_GZipWriteArrayDefinition(layout->array_definition + i, gzfp)) {
        SDDS_SetError("Unable to write layout--error writing array definition (SDDS_WriteLayout)");
        return 0;
      }
 
    for (i = 0; i < layout->n_columns; i++)
      if (!SDDS_GZipWriteColumnDefinition(layout->column_definition + i, gzfp)) {
        SDDS_SetError("Unable to write layout--error writing column definition (SDDS_WriteLayout)");
        return 0;
      }
 
#  if RW_ASSOCIATES != 0
    for (i = 0; i < layout->n_associates; i++)
      if (!SDDS_GZipWriteAssociateDefinition(layout->associate_definition + i, gzfp)) {
        SDDS_SetError("Unable to write layout--error writing associated file data (SDDS_WriteLayout)");
        return 0;
      }
#  endif
 
    if (!SDDS_GZipWriteDataMode(layout, gzfp)) {
      SDDS_SetError("Unable to write layout--error writing data mode (SDDS_WriteLayout)");
      return 0;
    }
 
    layout->layout_written = 1;
    /*gzflush(gzfp, Z_FULL_FLUSH); */
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!(lzmafp = layout->lzmafp)) {
        SDDS_SetError("Can't write SDDS layout--file pointer is NULL (SDDS_WriteLayout)");
        return 0;
      }
 
      /* write out the layout data */
      if (!SDDS_LZMAWriteVersion(layout->version, lzmafp)) {
        SDDS_SetError("Can't write SDDS layout--error writing version (SDDS_WriteLayout)");
        return 0;
      }
      if (layout->version < 3) {
        if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY) {
          if (layout->byteOrderDeclared == SDDS_BIGENDIAN)
            lzma_printf(lzmafp, "!# big-endian\n");
          else
            lzma_printf(lzmafp, "!# little-endian\n");
        }
        if (SDDS_dataset->layout.data_mode.fixed_row_count) {
          lzma_printf(lzmafp, "!# fixed-rowcount\n");
        }
      }
      if (!SDDS_LZMAWriteDescription(layout->description, layout->contents, lzmafp)) {
        SDDS_SetError("Can't write SDDS layout--error writing description (SDDS_WriteLayout)");
        return 0;
      }
      for (i = 0; i < layout->n_parameters; i++)
        if (!SDDS_LZMAWriteParameterDefinition(layout->parameter_definition + i, lzmafp)) {
          SDDS_SetError("Unable to write layout--error writing parameter definition (SDDS_WriteLayout)");
          return 0;
        }
      for (i = 0; i < layout->n_arrays; i++)
        if (!SDDS_LZMAWriteArrayDefinition(layout->array_definition + i, lzmafp)) {
          SDDS_SetError("Unable to write layout--error writing array definition (SDDS_WriteLayout)");
          return 0;
        }
      for (i = 0; i < layout->n_columns; i++)
        if (!SDDS_LZMAWriteColumnDefinition(layout->column_definition + i, lzmafp)) {
          SDDS_SetError("Unable to write layout--error writing column definition (SDDS_WriteLayout)");
          return 0;
        }
 
#if RW_ASSOCIATES != 0
      for (i = 0; i < layout->n_associates; i++)
        if (!SDDS_LZMAWriteAssociateDefinition(layout->associate_definition + i, lzmafp)) {
          SDDS_SetError("Unable to write layout--error writing associated file data (SDDS_WriteLayout)");
          return 0;
        }
#endif
 
      if (!SDDS_LZMAWriteDataMode(layout, lzmafp)) {
        SDDS_SetError("Unable to write layout--error writing data mode (SDDS_WriteLayout)");
        return 0;
      }
 
      layout->layout_written = 1;
    } else {
 
      if (!(fp = layout->fp)) {
        SDDS_SetError("Can't write SDDS layout--file pointer is NULL (SDDS_WriteLayout)");
        return 0;
      }
 
      /* write out the layout data */
      if (!SDDS_WriteVersion(layout->version, fp)) {
        SDDS_SetError("Can't write SDDS layout--error writing version (SDDS_WriteLayout)");
        return 0;
      }
      if (layout->version < 3) {
        if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY) {
          if (layout->byteOrderDeclared == SDDS_BIGENDIAN)
            fprintf(fp, "!# big-endian\n");
          else
            fprintf(fp, "!# little-endian\n");
        }
        if (SDDS_dataset->layout.data_mode.fixed_row_count) {
          fprintf(fp, "!# fixed-rowcount\n");
        }
      }
      if (!SDDS_WriteDescription(layout->description, layout->contents, fp)) {
        SDDS_SetError("Can't write SDDS layout--error writing description (SDDS_WriteLayout)");
        return 0;
      }
 
      for (i = 0; i < layout->n_parameters; i++)
        if (!SDDS_WriteParameterDefinition(layout->parameter_definition + i, fp)) {
          SDDS_SetError("Unable to write layout--error writing parameter definition (SDDS_WriteLayout)");
          return 0;
        }
 
      for (i = 0; i < layout->n_arrays; i++)
        if (!SDDS_WriteArrayDefinition(layout->array_definition + i, fp)) {
          SDDS_SetError("Unable to write layout--error writing array definition (SDDS_WriteLayout)");
          return 0;
        }
 
      for (i = 0; i < layout->n_columns; i++)
        if (!SDDS_WriteColumnDefinition(layout->column_definition + i, fp)) {
          SDDS_SetError("Unable to write layout--error writing column definition (SDDS_WriteLayout)");
          return 0;
        }
 
#if RW_ASSOCIATES != 0
      for (i = 0; i < layout->n_associates; i++)
        if (!SDDS_WriteAssociateDefinition(layout->associate_definition + i, fp)) {
          SDDS_SetError("Unable to write layout--error writing associated file data (SDDS_WriteLayout)");
          return 0;
        }
#endif
 
      if (!SDDS_WriteDataMode(layout, fp)) {
        SDDS_SetError("Unable to write layout--error writing data mode (SDDS_WriteLayout)");
        return 0;
      }
 
      layout->layout_written = 1;
      fflush(fp);
    }
#if defined(zLib)
  }
#endif
  if (SDDS_SyncDataSet(SDDS_dataset) != 0)
    return 0;
  return (1);
}

SDDS_WriteNonNativeBinaryArrays()

int32_t SDDS_WriteNonNativeBinaryArrays

(

SDDS_DATASET *

SDDS_dataset

)

Writes non-native endian binary arrays to an SDDS dataset.

This function iterates through all array definitions in the specified SDDS dataset and writes their binary data to the underlying file. It handles various data types, including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. For string arrays, it writes each string individually, ensuring proper memory management and byte order conversion. The function supports different compression formats, including uncompressed, LZMA-compressed, and GZIP-compressed files. After writing, it swaps the endianness of the array data to match the system's native byte order.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to write to.

Returns

int32_t Returns 1 on successful writing of all arrays, or 0 if an error occurred.

Return values

1	All non-native endian arrays were successfully written and byte-swapped.
0	An error occurred during the write operation, such as I/O failures, memory allocation issues, or corrupted array definitions.

Note

This function modifies the dataset's array data during the write process. Ensure that the dataset is properly initialized and opened for writing before invoking this function. After writing, the dataset's state is updated to reflect the written arrays.

Definition at line 5477 of file SDDS_binary.c.

                                                                    {
  int32_t i, j, dimension, zero = 0;
  SDDS_LAYOUT *layout;
  FILE *fp;
  struct lzmafile *lzmafp;
  SDDS_FILEBUFFER *fBuffer;
#if defined(zLib)
  gzFile gzfp;
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_WriteNonNativeBinaryArrays"))
    return (0);
  SDDS_SwapEndsArrayData(SDDS_dataset);
 
  layout = &SDDS_dataset->layout;
  fBuffer = &SDDS_dataset->fBuffer;
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    gzfp = layout->gzfp;
    for (i = 0; i < layout->n_arrays; i++) {
      if (!SDDS_dataset->array[i].dimension) {
        for (j = 0; j < layout->array_definition[i].dimensions; j++)
          if (!SDDS_GZipBufferedWrite(&zero, sizeof(zero), gzfp, fBuffer)) {
            SDDS_SetError("Unable to write null array--failure writing dimensions (SDDS_WriteNonNativeBinaryArrays)");
            SDDS_SwapEndsArrayData(SDDS_dataset);
            return 0;
          }
        continue;
      }
 
      for (j = 0; j < layout->array_definition[i].dimensions; j++) {
        dimension = SDDS_dataset->array[i].dimension[j];
        SDDS_SwapLong(&dimension);
        if (!SDDS_GZipBufferedWrite(&dimension, sizeof(dimension), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write arrays--failure writing dimensions (SDDS_WriteNonNativeBinaryArrays)");
          SDDS_SwapEndsArrayData(SDDS_dataset);
          return (0);
        }
      }
      if (layout->array_definition[i].type == SDDS_STRING) {
        for (j = 0; j < SDDS_dataset->array[i].elements; j++) {
          if (!SDDS_GZipWriteNonNativeBinaryString(((char **)SDDS_dataset->array[i].data)[j], gzfp, fBuffer)) {
            SDDS_SetError("Unable to write arrays--failure writing string (SDDS_WriteNonNativeBinaryArrays)");
            SDDS_SwapEndsArrayData(SDDS_dataset);
            return (0);
          }
        }
      } else if (!SDDS_GZipBufferedWrite(SDDS_dataset->array[i].data, SDDS_type_size[layout->array_definition[i].type - 1] * SDDS_dataset->array[i].elements, gzfp, fBuffer)) {
        SDDS_SetError("Unable to write arrays--failure writing values (SDDS_WriteNonNativeBinaryArrays)");
        SDDS_SwapEndsArrayData(SDDS_dataset);
        return (0);
      }
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      lzmafp = layout->lzmafp;
      for (i = 0; i < layout->n_arrays; i++) {
        if (!SDDS_dataset->array[i].dimension) {
          for (j = 0; j < layout->array_definition[i].dimensions; j++)
            if (!SDDS_LZMABufferedWrite(&zero, sizeof(zero), lzmafp, fBuffer)) {
              SDDS_SetError("Unable to write null array--failure writing dimensions (SDDS_WriteNonNativeBinaryArrays)");
              SDDS_SwapEndsArrayData(SDDS_dataset);
              return 0;
            }
          continue;
        }
 
        for (j = 0; j < layout->array_definition[i].dimensions; j++) {
          dimension = SDDS_dataset->array[i].dimension[j];
          SDDS_SwapLong(&dimension);
          if (!SDDS_LZMABufferedWrite(&dimension, sizeof(dimension), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write arrays--failure writing dimensions (SDDS_WriteNonNativeBinaryArrays)");
            SDDS_SwapEndsArrayData(SDDS_dataset);
            return (0);
          }
        }
        if (layout->array_definition[i].type == SDDS_STRING) {
          for (j = 0; j < SDDS_dataset->array[i].elements; j++) {
            if (!SDDS_LZMAWriteNonNativeBinaryString(((char **)SDDS_dataset->array[i].data)[j], lzmafp, fBuffer)) {
              SDDS_SetError("Unable to write arrays--failure writing string (SDDS_WriteNonNativeBinaryArrays)");
              SDDS_SwapEndsArrayData(SDDS_dataset);
              return (0);
            }
          }
        } else if (!SDDS_LZMABufferedWrite(SDDS_dataset->array[i].data, SDDS_type_size[layout->array_definition[i].type - 1] * SDDS_dataset->array[i].elements, lzmafp, fBuffer)) {
          SDDS_SetError("Unable to write arrays--failure writing values (SDDS_WriteNonNativeBinaryArrays)");
          SDDS_SwapEndsArrayData(SDDS_dataset);
          return (0);
        }
      }
    } else {
      fp = layout->fp;
      for (i = 0; i < layout->n_arrays; i++) {
        if (!SDDS_dataset->array[i].dimension) {
          for (j = 0; j < layout->array_definition[i].dimensions; j++)
            if (!SDDS_BufferedWrite(&zero, sizeof(zero), fp, fBuffer)) {
              SDDS_SetError("Unable to write null array--failure writing dimensions (SDDS_WriteNonNativeBinaryArrays)");
              SDDS_SwapEndsArrayData(SDDS_dataset);
              return 0;
            }
          continue;
        }
 
        for (j = 0; j < layout->array_definition[i].dimensions; j++) {
          dimension = SDDS_dataset->array[i].dimension[j];
          SDDS_SwapLong(&dimension);
          if (!SDDS_BufferedWrite(&dimension, sizeof(dimension), fp, fBuffer)) {
            SDDS_SetError("Unable to write arrays--failure writing dimensions (SDDS_WriteNonNativeBinaryArrays)");
            SDDS_SwapEndsArrayData(SDDS_dataset);
            return (0);
          }
        }
        if (layout->array_definition[i].type == SDDS_STRING) {
          for (j = 0; j < SDDS_dataset->array[i].elements; j++) {
            if (!SDDS_WriteNonNativeBinaryString(((char **)SDDS_dataset->array[i].data)[j], fp, fBuffer)) {
              SDDS_SetError("Unable to write arrays--failure writing string (SDDS_WriteNonNativeBinaryArrays)");
              SDDS_SwapEndsArrayData(SDDS_dataset);
              return (0);
            }
          }
        } else if (!SDDS_BufferedWrite(SDDS_dataset->array[i].data, SDDS_type_size[layout->array_definition[i].type - 1] * SDDS_dataset->array[i].elements, fp, fBuffer)) {
          SDDS_SetError("Unable to write arrays--failure writing values (SDDS_WriteNonNativeBinaryArrays)");
          SDDS_SwapEndsArrayData(SDDS_dataset);
          return (0);
        }
      }
    }
#if defined(zLib)
  }
#endif
  SDDS_SwapEndsArrayData(SDDS_dataset);
  return (1);
}

SDDS_WriteNonNativeBinaryPage()

epicsShareFuncSDDS int32_t SDDS_WriteNonNativeBinaryPage ( SDDS_DATASET * SDDS_dataset )

extern

Writes a non-native endian binary page to an SDDS dataset.

This function writes a binary page to the specified SDDS dataset, handling byte order reversal to convert between little-endian and big-endian formats. It manages various compression formats, including uncompressed, GZIP-compressed, and LZMA-compressed files. The function performs the following operations:

• Counts the number of rows to write.
• Writes the row count with appropriate byte order handling.
• Writes non-native endian parameters and arrays.
• Writes column data in either column-major or row-major format based on the dataset's configuration.
• Flushes the buffer to ensure all data is written to the file.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to write to.

Returns

int32_t Returns 1 on successful writing of the binary page, or 0 if an error occurred.

Return values

1	The binary page was successfully written and byte-swapped.
0	An error occurred during the write operation, such as I/O failures, memory allocation issues, or corrupted dataset definitions.

Note

This function modifies the dataset's internal structures during the write process. Ensure that the dataset is properly initialized and opened for writing before invoking this function. After writing, the dataset's state is updated to reflect the newly written page.

Definition at line 5112 of file SDDS_binary.c.

{
  FILE *fp;
  struct lzmafile *lzmafp = NULL;
  int64_t i, rows, fixed_rows;
  int32_t min32 = INT32_MIN, rows32;
  SDDS_FILEBUFFER *fBuffer;
#if defined(zLib)
  gzFile gzfp = NULL;
#endif
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_WriteNonNativeBinaryPage"))
    return (0);
  if (!(fp = SDDS_dataset->layout.fp)) {
    SDDS_SetError("Unable to write page--file pointer is NULL (SDDS_WriteNonNativeBinaryPage)");
    return (0);
  }
  fBuffer = &SDDS_dataset->fBuffer;
 
  if (!fBuffer->buffer) {
    int32_t bufferSize = SDDS_GetLockedDefaultIOBufferSize();
    if (!(fBuffer->buffer = fBuffer->data = SDDS_Malloc(sizeof(char) * bufferSize))) {
      SDDS_SetError("Unable to do buffered read--allocation failure (SDDS_WriteNonNativeBinaryPage)");
      return 0;
    }
    fBuffer->bufferSize = bufferSize;
    fBuffer->bytesLeft = bufferSize;
  }
  SDDS_SwapLong(&min32);
 
  rows = SDDS_CountRowsOfInterest(SDDS_dataset);
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!(gzfp = SDDS_dataset->layout.gzfp)) {
      SDDS_SetError("Unable to write page--file pointer is NULL (SDDS_WriteNonNativeBinaryPage)");
      return (0);
    }
    SDDS_dataset->rowcount_offset = gztell(gzfp);
    if (SDDS_dataset->layout.data_mode.fixed_row_count) {
      fixed_rows = ((rows / SDDS_dataset->layout.data_mode.fixed_row_increment) + 2) * SDDS_dataset->layout.data_mode.fixed_row_increment;
      if (fixed_rows > INT32_MAX) {
        if (!SDDS_GZipBufferedWrite(&min32, sizeof(min32), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
          return (0);
        }
        SDDS_SwapLong64(&fixed_rows);
        if (!SDDS_GZipBufferedWrite(&fixed_rows, sizeof(fixed_rows), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
          return (0);
        }
        SDDS_SwapLong64(&fixed_rows);
      } else {
        rows32 = (int32_t)fixed_rows;
        SDDS_SwapLong(&rows32);
        if (!SDDS_GZipBufferedWrite(&rows32, sizeof(rows32), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
          return (0);
        }
      }
    } else {
      if (rows > INT32_MAX) {
        if (!SDDS_GZipBufferedWrite(&min32, sizeof(min32), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
          return (0);
        }
        SDDS_SwapLong64(&rows);
        if (!SDDS_GZipBufferedWrite(&rows, sizeof(rows), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
          return (0);
        }
        SDDS_SwapLong64(&rows);
      } else {
        rows32 = (int32_t)rows;
        SDDS_SwapLong(&rows32);
        if (!SDDS_GZipBufferedWrite(&rows32, sizeof(rows32), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
          return (0);
        }
      }
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!(lzmafp = SDDS_dataset->layout.lzmafp)) {
        SDDS_SetError("Unable to write page--file pointer is NULL (SDDS_WriteNonNativeBinaryPage)");
        return (0);
      }
      SDDS_dataset->rowcount_offset = lzma_tell(lzmafp);
      if (SDDS_dataset->layout.data_mode.fixed_row_count) {
        fixed_rows = ((rows / SDDS_dataset->layout.data_mode.fixed_row_increment) + 2) * SDDS_dataset->layout.data_mode.fixed_row_increment;
        if (fixed_rows > INT32_MAX) {
          if (!SDDS_LZMABufferedWrite(&min32, sizeof(min32), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&fixed_rows);
          if (!SDDS_LZMABufferedWrite(&fixed_rows, sizeof(fixed_rows), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&fixed_rows);
        } else {
          rows32 = (int32_t)fixed_rows;
          SDDS_SwapLong(&rows32);
          if (!SDDS_LZMABufferedWrite(&rows32, sizeof(rows32), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
        }
      } else {
        if (rows > INT32_MAX) {
          if (!SDDS_LZMABufferedWrite(&min32, sizeof(min32), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&rows);
          if (!SDDS_LZMABufferedWrite(&rows, sizeof(rows), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&rows);
        } else {
          rows32 = (int32_t)rows;
          SDDS_SwapLong(&rows32);
          if (!SDDS_LZMABufferedWrite(&rows32, sizeof(rows32), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
        }
      }
    } else {
      SDDS_dataset->rowcount_offset = ftell(fp);
      if (SDDS_dataset->layout.data_mode.fixed_row_count) {
        fixed_rows = ((rows / SDDS_dataset->layout.data_mode.fixed_row_increment) + 2) * SDDS_dataset->layout.data_mode.fixed_row_increment;
        if (fixed_rows > INT32_MAX) {
          if (!SDDS_BufferedWrite(&min32, sizeof(min32), fp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&fixed_rows);
          if (!SDDS_BufferedWrite(&fixed_rows, sizeof(fixed_rows), fp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&fixed_rows);
        } else {
          rows32 = (int32_t)fixed_rows;
          SDDS_SwapLong(&rows32);
          if (!SDDS_BufferedWrite(&rows32, sizeof(rows32), fp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
        }
      } else {
        if (rows > INT32_MAX) {
          if (!SDDS_BufferedWrite(&min32, sizeof(min32), fp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&rows);
          if (!SDDS_BufferedWrite(&rows, sizeof(rows), fp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
          SDDS_SwapLong64(&rows);
        } else {
          rows32 = (int32_t)rows;
          SDDS_SwapLong(&rows32);
          if (!SDDS_BufferedWrite(&rows32, sizeof(rows32), fp, fBuffer)) {
            SDDS_SetError("Unable to write page--failure writing number of rows (SDDS_WriteNonNativeBinaryPage)");
            return (0);
          }
        }
      }
    }
#if defined(zLib)
  }
#endif
  if (!SDDS_WriteNonNativeBinaryParameters(SDDS_dataset)) {
    SDDS_SetError("Unable to write page--parameter writing problem (SDDS_WriteNonNativeBinaryPage)");
    return 0;
  }
  if (!SDDS_WriteNonNativeBinaryArrays(SDDS_dataset)) {
    SDDS_SetError("Unable to write page--array writing problem (SDDS_WriteNonNativeBinaryPage)");
    return 0;
  }
  SDDS_SwapEndsColumnData(SDDS_dataset);
  if (SDDS_dataset->layout.n_columns) {
    if (SDDS_dataset->layout.data_mode.column_major) {
      if (!SDDS_WriteNonNativeBinaryColumns(SDDS_dataset)) {
        SDDS_SetError("Unable to write page--column writing problem (SDDS_WriteNonNativeBinaryPage)");
        return 0;
      }
    } else {
      for (i = 0; i < SDDS_dataset->n_rows; i++) {
        if (SDDS_dataset->row_flag[i]) {
          if (!SDDS_WriteNonNativeBinaryRow(SDDS_dataset, i)) {
            SDDS_SetError("Unable to write page--row writing problem (SDDS_WriteNonNativeBinaryPage)");
            return 0;
          }
        }
      }
    }
  }
  SDDS_SwapEndsColumnData(SDDS_dataset);
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!SDDS_GZipFlushBuffer(gzfp, fBuffer)) {
      SDDS_SetError("Unable to write page--buffer flushing problem (SDDS_WriteNonNativeBinaryPage)");
      return 0;
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!SDDS_LZMAFlushBuffer(lzmafp, fBuffer)) {
        SDDS_SetError("Unable to write page--buffer flushing problem (SDDS_WriteNonNativeBinaryPage)");
        return 0;
      }
    } else {
      if (!SDDS_FlushBuffer(fp, fBuffer)) {
        SDDS_SetError("Unable to write page--buffer flushing problem (SDDS_WriteNonNativeBinaryPage)");
        return 0;
      }
    }
#if defined(zLib)
  }
#endif
  SDDS_dataset->last_row_written = SDDS_dataset->n_rows - 1;
  SDDS_dataset->n_rows_written = rows;
  SDDS_dataset->writing_page = 1;
  return (1);
}

SDDS_WriteNonNativeBinaryParameters()

int32_t SDDS_WriteNonNativeBinaryParameters

(

SDDS_DATASET *

SDDS_dataset

)

Writes non-native endian binary parameters to an SDDS dataset.

This function iterates through all parameter definitions in the specified SDDS dataset and writes their binary data to the underlying file. It handles various data types, including short, unsigned short, long, unsigned long, long long, unsigned long long, float, double, and long double. For string parameters, it writes each string individually, ensuring proper memory management and byte order conversion. Parameters with fixed values are skipped during the write process. The function supports different compression formats, including uncompressed, LZMA-compressed, and GZIP-compressed files.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset to write to.

Returns

int32_t Returns 1 on successful writing of all parameters, or 0 if an error occurred.

Return values

1	All non-native endian parameters were successfully written and byte-swapped.
0	An error occurred during the write operation, such as I/O failures, memory allocation issues, or corrupted parameter definitions.

Note

This function modifies the dataset's parameter data during the write process. Ensure that the dataset is properly initialized and opened for writing before invoking this function. After writing, the dataset's state is updated to reflect the written parameters.

Definition at line 5369 of file SDDS_binary.c.

                                                                        {
  int32_t i;
  SDDS_LAYOUT *layout;
  FILE *fp;
  struct lzmafile *lzmafp;
  SDDS_FILEBUFFER *fBuffer;
#if defined(zLib)
  gzFile gzfp;
#endif
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_WriteNonNativeBinaryParameters"))
    return (0);
 
  SDDS_SwapEndsParameterData(SDDS_dataset);
 
  layout = &SDDS_dataset->layout;
  fBuffer = &SDDS_dataset->fBuffer;
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    if (!(gzfp = layout->gzfp)) {
      SDDS_SetError("Unable to write parameters--file pointer is NULL (SDDS_WriteNonNativeBinaryParameters)");
      return (0);
    }
    for (i = 0; i < layout->n_parameters; i++) {
      if (layout->parameter_definition[i].fixed_value)
        continue;
      if (layout->parameter_definition[i].type == SDDS_STRING) {
        if (!SDDS_GZipWriteNonNativeBinaryString(*((char **)SDDS_dataset->parameter[i]), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write parameters--failure writing string (SDDS_WriteNonNativeBinaryParameters)");
          SDDS_SwapEndsParameterData(SDDS_dataset);
          return (0);
        }
      } else if (!SDDS_GZipBufferedWrite(SDDS_dataset->parameter[i], SDDS_type_size[layout->parameter_definition[i].type - 1], gzfp, fBuffer)) {
        SDDS_SetError("Unable to write parameters--failure writing value (SDDS_WriteBinaryParameters)");
        SDDS_SwapEndsParameterData(SDDS_dataset);
        return (0);
      }
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      if (!(lzmafp = layout->lzmafp)) {
        SDDS_SetError("Unable to write parameters--file pointer is NULL (SDDS_WriteNonNativeBinaryParameters)");
        return (0);
      }
      for (i = 0; i < layout->n_parameters; i++) {
        if (layout->parameter_definition[i].fixed_value)
          continue;
        if (layout->parameter_definition[i].type == SDDS_STRING) {
          if (!SDDS_LZMAWriteNonNativeBinaryString(*((char **)SDDS_dataset->parameter[i]), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write parameters--failure writing string (SDDS_WriteNonNativeBinaryParameters)");
            SDDS_SwapEndsParameterData(SDDS_dataset);
            return (0);
          }
        } else if (!SDDS_LZMABufferedWrite(SDDS_dataset->parameter[i], SDDS_type_size[layout->parameter_definition[i].type - 1], lzmafp, fBuffer)) {
          SDDS_SetError("Unable to write parameters--failure writing value (SDDS_WriteBinaryParameters)");
          SDDS_SwapEndsParameterData(SDDS_dataset);
          return (0);
        }
      }
    } else {
      fp = layout->fp;
      for (i = 0; i < layout->n_parameters; i++) {
        if (layout->parameter_definition[i].fixed_value)
          continue;
        if (layout->parameter_definition[i].type == SDDS_STRING) {
          if (!SDDS_WriteNonNativeBinaryString(*((char **)SDDS_dataset->parameter[i]), fp, fBuffer)) {
            SDDS_SetError("Unable to write parameters--failure writing string (SDDS_WriteNonNativeBinaryParameters)");
            SDDS_SwapEndsParameterData(SDDS_dataset);
            return (0);
          }
        } else if (!SDDS_BufferedWrite(SDDS_dataset->parameter[i], SDDS_type_size[layout->parameter_definition[i].type - 1], fp, fBuffer)) {
          SDDS_SetError("Unable to write parameters--failure writing value (SDDS_WriteBinaryParameters)");
          SDDS_SwapEndsParameterData(SDDS_dataset);
          return (0);
        }
      }
    }
#if defined(zLib)
  }
#endif
 
  SDDS_SwapEndsParameterData(SDDS_dataset);
  return (1);
}

SDDS_WriteNonNativeBinaryRow()

int32_t SDDS_WriteNonNativeBinaryRow	(	SDDS_DATASET *	SDDS_dataset,
		int64_t	row )

Writes a non-native endian binary row to an SDDS dataset.

This function writes a single row of data to the specified SDDS dataset, handling byte order reversal to convert between little-endian and big-endian formats. It supports various compression formats, including uncompressed, GZIP-compressed, and LZMA-compressed files. The function iterates through all column definitions, writing each column's data appropriately based on its type. For string columns, it ensures proper memory management and byte order conversion by utilizing specialized string writing functions. For non-string data types, it writes the binary data directly with the correct byte ordering.

Parameters

[in,out]	SDDS_dataset	Pointer to the SDDS_DATASET structure representing the dataset to write to.
[in]	row	The index of the row to write to the dataset.

Returns

int32_t Returns 1 on successful writing of the binary row, or 0 if an error occurred.

Return values

1	The binary row was successfully written and byte-swapped.
0	An error occurred during the write operation, such as I/O failures or corrupted data.

Note

This function modifies the dataset's internal data structures during the write process. Ensure that the dataset is properly initialized and opened for writing before invoking this function. After writing, the dataset's state is updated to reflect the newly written row.

Definition at line 5632 of file SDDS_binary.c.

                                                                              {
  int64_t i, type, size;
  SDDS_LAYOUT *layout;
  FILE *fp;
  struct lzmafile *lzmafp;
  SDDS_FILEBUFFER *fBuffer;
#if defined(zLib)
  gzFile gzfp;
#endif
 
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_WriteNonNativeBinaryRow"))
    return (0);
  layout = &SDDS_dataset->layout;
  fBuffer = &SDDS_dataset->fBuffer;
#if defined(zLib)
  if (SDDS_dataset->layout.gzipFile) {
    gzfp = layout->gzfp;
    for (i = 0; i < layout->n_columns; i++) {
      if ((type = layout->column_definition[i].type) == SDDS_STRING) {
        if (!SDDS_GZipWriteNonNativeBinaryString(*((char **)SDDS_dataset->data[i] + row), gzfp, fBuffer)) {
          SDDS_SetError("Unable to write rows--failure writing string (SDDS_WriteNonNativeBinaryRows)");
          return (0);
        }
      } else {
        size = SDDS_type_size[type - 1];
        if (!SDDS_GZipBufferedWrite((char *)SDDS_dataset->data[i] + row * size, size, gzfp, fBuffer)) {
          SDDS_SetError("Unable to write row--failure writing value (SDDS_WriteNonNativeBinaryRow)");
          return (0);
        }
      }
    }
  } else {
#endif
    if (SDDS_dataset->layout.lzmaFile) {
      lzmafp = layout->lzmafp;
      for (i = 0; i < layout->n_columns; i++) {
        if ((type = layout->column_definition[i].type) == SDDS_STRING) {
          if (!SDDS_LZMAWriteNonNativeBinaryString(*((char **)SDDS_dataset->data[i] + row), lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write rows--failure writing string (SDDS_WriteNonNativeBinaryRows)");
            return (0);
          }
        } else {
          size = SDDS_type_size[type - 1];
          if (!SDDS_LZMABufferedWrite((char *)SDDS_dataset->data[i] + row * size, size, lzmafp, fBuffer)) {
            SDDS_SetError("Unable to write row--failure writing value (SDDS_WriteNonNativeBinaryRow)");
            return (0);
          }
        }
      }
    } else {
      fp = layout->fp;
      for (i = 0; i < layout->n_columns; i++) {
        if ((type = layout->column_definition[i].type) == SDDS_STRING) {
          if (!SDDS_WriteNonNativeBinaryString(*((char **)SDDS_dataset->data[i] + row), fp, fBuffer)) {
            SDDS_SetError("Unable to write rows--failure writing string (SDDS_WriteNonNativeBinaryRows)");
            return (0);
          }
        } else {
          size = SDDS_type_size[type - 1];
          if (!SDDS_BufferedWrite((char *)SDDS_dataset->data[i] + row * size, size, fp, fBuffer)) {
            SDDS_SetError("Unable to write row--failure writing value (SDDS_WriteNonNativeBinaryRow)");
            return (0);
          }
        }
      }
    }
#if defined(zLib)
  }
#endif
  return (1);
}

SDDS_WriteNonNativeBinaryString()

int32_t SDDS_WriteNonNativeBinaryString	(	char *	string,
		FILE *	fp,
		SDDS_FILEBUFFER *	fBuffer )

Writes a non-native endian binary string to a file.

This function writes a binary string to the specified file pointer, handling non-native endianness. It first writes the length of the string as a 32-bit integer with byte order swapped. If the string is not to be skipped, it then writes the string data itself followed by a null terminator. If the input string is NULL, an empty string is written instead.

Parameters

[in]	string	The string to write. If NULL, an empty string is written.
[in]	fp	Pointer to the FILE where the string will be written.
[in]	fBuffer	Pointer to the SDDS_FILEBUFFER structure used for buffered writing.

Returns

int32_t Returns 1 on successful writing of the string, or 0 if an error occurred.

Return values

1	The string was successfully written and byte-swapped.
0	An error occurred during the write operation, such as I/O failures or memory allocation issues.

Note

The caller is responsible for ensuring that the file pointer fp is valid and open for writing. This function does not perform memory allocation for the string; it assumes that the string is already allocated and managed appropriately.

Definition at line 5724 of file SDDS_binary.c.

                                                                                          {
  int32_t length;
  static const char dummy_string[] = "";
  if (!string)
    string = (char *)dummy_string;
  length = strlen(string);
  SDDS_SwapLong(&length);
  if (!SDDS_BufferedWrite(&length, sizeof(length), fp, fBuffer)) {
    SDDS_SetError("Unable to write string--error writing length");
    return (0);
  }
  SDDS_SwapLong(&length);
  if (length && !SDDS_BufferedWrite(string, sizeof(*string) * length, fp, fBuffer)) {
    SDDS_SetError("Unable to write string--error writing contents");
    return (0);
  }
  return (1);
}

SDDS_WritePage()

epicsShareFuncSDDS int32_t SDDS_WritePage ( SDDS_DATASET * SDDS_dataset )

extern

Writes the current data table to the output file.

This function serializes and writes the current data table of the SDDS dataset to the output file. It must be preceded by a call to SDDS_WriteLayout to ensure that the dataset layout is properly defined in the output file. Depending on the data mode (ASCII or Binary), the function delegates the writing process to the appropriate handler.

Parameters

[in,out]

SDDS_dataset

Pointer to the SDDS_DATASET structure representing the dataset.

Returns

• 1 on successful writing of the data table.
• 0 if an error occurred during the write process. An error message is set internally in this case.

Precondition

• The dataset must be initialized and configured for output.
• SDDS_WriteLayout must have been called successfully before writing any pages.

Postcondition

• The current data table is written to the output file.
• The dataset state is synchronized with the file to ensure data integrity.

Note

• The function supports parallel I/O modes if enabled.
• Ensure that the dataset is not disconnected from the output file before calling this function.

Warning

• Attempting to write a page without defining the layout first will result in an error.
• Concurrent access to the dataset while writing pages may lead to undefined behavior.

Definition at line 1229 of file SDDS_output.c.

                                                   {
  int32_t result;
#if SDDS_MPI_IO
  if (SDDS_dataset->parallel_io)
    return SDDS_MPI_WritePage(SDDS_dataset);
#endif
  if (!SDDS_CheckDataset(SDDS_dataset, "SDDS_WritePage"))
    return 0;
  if (!SDDS_dataset->layout.layout_written) {
    SDDS_SetError("Unable to write page--layout not written (SDDS_WritePage)");
    return 0;
  }
  if (SDDS_dataset->layout.disconnected) {
    SDDS_SetError("Can't write page--file is disconnected (SDDS_WritePage)");
    return 0;
  }
  if (SDDS_dataset->layout.data_mode.mode == SDDS_ASCII)
    result = SDDS_WriteAsciiPage(SDDS_dataset);
  else if (SDDS_dataset->layout.data_mode.mode == SDDS_BINARY)
    result = SDDS_WriteBinaryPage(SDDS_dataset);
  else {
    SDDS_SetError("Unable to write page--unknown data mode (SDDS_WritePage)");
    return 0;
  }
  if (result == 1)
    if (SDDS_SyncDataSet(SDDS_dataset) != 0)
      return 0;
  return (result);
}

SDDS_WriteTypedValue()

epicsShareFuncSDDS int32_t SDDS_WriteTypedValue ( void * data, int64_t index, int32_t type, char * format, FILE * fp )

extern

Writes a typed value to an ASCII file stream.

This function writes a value of a specified SDDS data type to an ASCII file stream. The data is provided as a void pointer, and the function handles various data types by casting the pointer appropriately based on the type parameter. For string data, special characters are escaped according to SDDS conventions.

Parameters

data	Pointer to the data to be written. Should be castable to the type specified by type.
index	Array index of the data to be printed; use 0 if not an array.
type	The SDDS data type of the data variable. Possible values include SDDS_SHORT, SDDS_LONG, SDDS_FLOAT, etc.
format	Optional printf format string to use; pass NULL to use the default format for the data type.
fp	The FILE pointer to the ASCII file stream where the data will be written.

Returns

Returns 1 on success; 0 on error (e.g., if data or fp is NULL, or an unknown data type is specified).

Definition at line 57 of file SDDS_ascii.c.

                                                                                              {
  char c, *s;
  short hasWhitespace;
 
  if (!data) {
    SDDS_SetError("Unable to write value--data pointer is NULL (SDDS_WriteTypedValue)");
    return (0);
  }
  if (!fp) {
    SDDS_SetError("Unable to print value--file pointer is NULL (SDDS_WriteTypedValue)");
    return (0);
  }
  switch (type) {
  case SDDS_SHORT:
    fprintf(fp, format ? format : "%hd", *((short *)data + index));
    break;
  case SDDS_USHORT:
    fprintf(fp, format ? format : "%hu", *((unsigned short *)data + index));
    break;
  case SDDS_LONG:
    fprintf(fp, format ? format : "%" PRId32, *((int32_t *)data + index));
    break;
  case SDDS_ULONG:
    fprintf(fp, format ? format : "%" PRIu32, *((uint32_t *)data + index));
    break;
  case SDDS_LONG64:
    fprintf(fp, format ? format : "%" PRId64, *((int64_t *)data + index));
    break;
  case SDDS_ULONG64:
    fprintf(fp, format ? format : "%" PRIu64, *((uint64_t *)data + index));
    break;
  case SDDS_FLOAT:
    fprintf(fp, format ? format : "%15.8e", *((float *)data + index));
    break;
  case SDDS_DOUBLE:
    fprintf(fp, format ? format : "%22.15e", *((double *)data + index));
    break;
  case SDDS_LONGDOUBLE:
    if (LDBL_DIG == 18) {
      fprintf(fp, format ? format : "%22.18Le", *((long double *)data + index));
    } else {
      fprintf(fp, format ? format : "%22.15Le", *((long double *)data + index));
    }
    break;
  case SDDS_STRING:
    /* ignores format string */
    s = *((char **)data + index);
    hasWhitespace = 0;
    if (SDDS_HasWhitespace(s) || SDDS_StringIsBlank(s)) {
      fputc('"', fp);
      hasWhitespace = 1;
    }
    while (s && *s) {
      c = *s++;
      if (c == '!')
        fputs("\\!", fp);
      else if (c == '\\')
        fputs("\\\\", fp);
      else if (c == '"')
        fputs("\\\"", fp);
      else if (c == ' ')
        fputc(' ', fp); /* don't escape plain spaces */
      else if (isspace(c) || !isprint(c))
        fprintf(fp, "\\%03o", c);
      else
        fputc(c, fp);
    }
    if (hasWhitespace)
      fputc('"', fp);
    break;
  case SDDS_CHARACTER:
    /* ignores format string */
    c = *((char *)data + index);
    if (c == '!')
      fputs("\\!", fp);
    else if (c == '\\')
      fputs("\\\\", fp);
    else if (c == '"')
      fputs("\\\"", fp);
    else if (!c || isspace(c) || !isprint(c))
      fprintf(fp, "\\%03o", c);
    else
      fputc(c, fp);
    break;
  default:
    SDDS_SetError("Unable to write value--unknown data type (SDDS_WriteTypedValue)");
    return (0);
  }
  return (1);
}

SDDS_ZeroMemory()

epicsShareFuncSDDS int32_t SDDS_ZeroMemory ( void * mem, int64_t n_bytes )

extern

Sets a block of memory to zero.

This function zero-initializes a specified number of bytes in a memory block. It is a wrapper around the standard memset function, providing a convenient way to clear memory.

Parameters

[in,out]	mem	Pointer to the memory block to be zeroed.
[in]	n_bytes	The number of bytes to set to zero.

Returns

Returns 1 on successful memory zeroing. Returns 0 if the input memory pointer mem is NULL.

Note

The function does not perform any bounds checking. It is the caller's responsibility to ensure that the memory block is large enough to accommodate n_bytes.

See also

memset

Definition at line 2051 of file SDDS_utils.c.

                                                    {
  if (mem) {
    memset(mem, 0, n_bytes);
    return 1;
  }
  return 0;
 
  /*
    char *c;
 
    if (!(c = (char*)mem))
    return(0);
    while (n_bytes--)
    *c++ = 0;
    return(1);
  */
}