6.39 SDDS_GetArray

• name:
  SDDS_GetArray
• description:
  Returns a pointer to a structure containing the data and other information about an array in the current data table of a data set.
• synopsis: #include ”SDDS.h”
  SDDS_ARRAY *SDDS_GetArray(SDDS_TABLE *SDDS_table, char *array_name, SDDS_ARRAY *memory);
  
  typedef struct {  
      /* pointer to the internally-stored structure: */  
      ARRAY_DEFINITION *definition;  
      int32_t *dimension;            /* sizes for each dimension */  
      int32_t elements;              /* total number of elements */  
      /* Address of new copy of array of data values, stored contiguously: */  
      void *data;  
      /* Address of n-dimensional pointer array into the new copy of data: */  
      void *pointer;  
  } SDDS_ARRAY;

• arguments:
  • SDDS_table: Address of the SDDS_TABLE structure for the data set.
  • array_name: A NULL-terminated character string giving the name of the array to return.
  • memory: Address of a SDDS_ARRAY structure into which to place the information. Preferred usage is to pass back a pointer that was originally returned by SDDS_GetArray. Otherwise, the user must initialize the pointers in the structure to NULL.
• return value:
  On success, returns a pointer to a SDDS_ARRAY structure. The contents of the structure point to newly-created copies of the information, with the exception of the definition field, which points to the internal copy. If memory is not NULL, the storage pointed to by the data and pointer fields of the structure *memory will be reused. The data pointer, should be cast to type data-type*, where data-type is the data type of the array. The preferred method is to use the pointer pointer, which should be cast to type data-type*n, where *n symbolizes a string of n asterisks, n being the number of dimensions of the array. Note that for type SDDS_STRING, data-type is char *.
  
  On failure, returns NULL and records an error message.
• see also:
  • SDDS_NumberOfErrors
  • SDDS_PrintErrors
  • SDDS_SetArray