Application Programmer’s Guide for SDDS Version 5

Michael Borland and Robert Soliday
Advanced Photon Source

August 3, 2026

SDDS is a file protocol for Self Describing Data Sets. This document describes Version 5 of the SDDS protocol and the C and C++ libraries that support it. It is intended for those who wish to develop programs that use SDDS files.

1 Definition of SDDS Protocol
 1.1 Structure of the SDDS Header
 1.2 Structure of SDDS ASCII Data Pages
 1.3 Structure of SDDS Binary Data Pages
2 Overview of C Library Routines
 2.1 Thread Safety
 2.2 Input Routines
 2.3 Output Routines
 2.4 Error Handling and Utilities
3 The SDDS++ C++ Library
 3.1 Building and Linking
 3.2 Object Model and Data Types
 3.3 Input Routines
 3.4 Output Routines
 3.5 Generalized I/O and Compression
 3.6 Append, Update, and Live Files
 3.7 Layout and Data Transformations
 3.8 Error Handling and Resource Limits
 3.9 Thread Safety
 3.10 Compatibility Interface and Examples
4 C++ Library Manual Pages
 4.1 sdds::typeOf and sdds::typeName
 4.2 sdds::convertScalar and sdds::convertValues
 4.3 sdds::Layout
 4.4 sdds::LayoutBuilder
 4.5 sdds::LayoutEditor
 4.6 sdds::FieldSelection, sdds::RowSlice, and sdds::ReadRequest
 4.7 sdds::Page construction and field access
 4.8 sdds::Page typed access
 4.9 sdds::RowView and sdds::RowMask
 4.10 sdds::Page row and field transformations
 4.11 sdds::ReaderOptions and sdds::ReaderLimits
 4.12 sdds::Reader creation
 4.13 sdds::Reader page reading
 4.14 sdds::Reader page indexing
 4.15 sdds::Reader live-file and lifecycle operations
 4.16 sdds::InputSource, sdds::OutputSink, and adapters
 4.17 sdds::WriterOptions
 4.18 sdds::Writer creation and append modes
 4.19 sdds::Writer page output
 4.20 sdds::Writer update and lifecycle operations
 4.21 sdds::convertUnits
 4.22 sdds::copyDataset
 4.23 sdds::Error and derived exceptions
5 Two Templates for C SDDS Application Organization
 5.1 Accessing Data Stored in an SDDS File
 5.2 SDDS Output of Internally-Generated Data
6 C Library Manual Pages
 6.1 SDDS_ArrayCount
 6.2 SDDS_Bomb
 6.3 SDDS_CastValue
 6.4 SDDS_CheckArray
 6.5 SDDS_CheckColumn
 6.6 SDDS_CheckParameter
 6.7 SDDS_ClearErrors
 6.8 SDDS_ColumnCount
 6.9 SDDS_ConvertToDouble
 6.10 SDDS_ConvertToLong
 6.11 SDDS_ConvertToLongDouble
 6.12 SDDS_CopyArrays
 6.13 SDDS_CopyColumns
 6.14 SDDS_CopyLayout
 6.15 SDDS_CopyPage
 6.16 SDDS_CopyParameters
 6.17 SDDS_CopyRowDirect
 6.18 SDDS_CopyRowsOfInterest
 6.19 SDDS_CopyString
 6.20 SDDS_CopyTable
 6.21 SDDS_CountRowsOfInterest
 6.22 SDDS_DefineArray
 6.23 SDDS_DefineColumn
 6.24 SDDS_DefineParameter
 6.25 SDDS_DefineParameter1
 6.26 SDDS_DefineSimpleColumn
 6.27 SDDS_DefineSimpleColumns
 6.28 SDDS_DefineSimpleParameter
 6.29 SDDS_DefineSimpleParameters
 6.30 SDDS_DeleteColumn
 6.31 SDDS_DeleteParameter
 6.32 SDDS_DeleteUnsetColumns
 6.33 SDDS_DeleteUnsetRows
 6.34 SDDS_DisconnectFile
 6.35 SDDS_FilterRowsOfInterest
 6.36 SDDS_FindArray
 6.37 SDDS_FindColumn
 6.38 SDDS_FindParameter
 6.39 SDDS_GetArray
 6.40 SDDS_GetArrayDefinition
 6.41 SDDS_GetArrayInDoubles
 6.42 SDDS_GetArrayInLong
 6.43 SDDS_GetArrayIndex
 6.44 SDDS_GetArrayInformation
 6.45 SDDS_GetArrayNames
 6.46 SDDS_GetArrayType
 6.47 SDDS_GetColumn
 6.48 SDDS_GetColumnDefinition
 6.49 SDDS_GetColumnInDoubles
 6.50 SDDS_GetColumnInFloats
 6.51 SDDS_GetColumnInLong
 6.52 SDDS_GetColumnInShort
 6.53 SDDS_GetColumnIndex
 6.54 SDDS_GetColumnInformation
 6.55 SDDS_GetColumnNames
 6.56 SDDS_GetColumnType
 6.57 SDDS_GetMatrixFromColumn
 6.58 SDDS_GetMatrixOfRows
 6.59 SDDS_GetParameter
 6.60 SDDS_GetParameterAsDouble
 6.61 SDDS_GetParameterAsLong
 6.62 SDDS_GetParameterAsLongDouble
 6.63 SDDS_GetParameterAsString
 6.64 SDDS_GetParameterByIndex
 6.65 SDDS_GetParameterDefinition
 6.66 SDDS_GetParameterIndex
 6.67 SDDS_GetParameterInformation
 6.68 SDDS_GetParameterNames
 6.69 SDDS_GetParameterType
 6.70 SDDS_GetRow
 6.71 SDDS_GetTypeSize
 6.72 SDDS_GetValue
 6.73 SDDS_InitializeAppend
 6.74 SDDS_InitializeAppendToPage
 6.75 SDDS_InitializeCopy
 6.76 SDDS_InitializeHeaderlessInput
 6.77 SDDS_InitializeInput
 6.78 SDDS_InitializeOutput
 6.79 SDDS_LengthenTable
 6.80 SDDS_Logic
 6.81 SDDS_NumberOfErrors
 6.82 SDDS_ParameterCount
 6.83 SDDS_PrintErrors
 6.84 SDDS_PrintTypedValue
 6.85 SDDS_ReadPage
 6.86 SDDS_ReadTable
 6.87 SDDS_Realloc
 6.88 SDDS_ReconnectFile
 6.89 SDDS_RegisterProgramName
 6.90 SDDS_RowCount
 6.91 SDDS_SaveLayout
 6.92 SDDS_SetArray
 6.93 SDDS_SetColumn
 6.94 SDDS_SetColumnFlags
 6.95 SDDS_SetColumnFromDoubles
 6.96 SDDS_SetColumnFromLongs
 6.97 SDDS_SetColumnsOfInterest
 6.98 SDDS_SetError
 6.99 SDDS_SetParameter
 6.100 SDDS_SetParameters
 6.101 SDDS_SetParametersFromDoubles
 6.102 SDDS_SetRowFlags
 6.103 SDDS_SetRowValues
 6.104 SDDS_SetRowsOfInterest
 6.105 SDDS_StartPage
 6.106 SDDS_StartTable
 6.107 SDDS_StringIsBlank
 6.108 SDDS_Terminate
 6.109 SDDS_TransferColumnDefinition
 6.110 SDDS_VerifyArrayExists
 6.111 SDDS_VerifyColumnExists
 6.112 SDDS_VerifyParameterExists
 6.113 SDDS_WriteLayout
 6.114 SDDS_WritePage
 6.115 SDDS_WriteTable
Contents