//--------------------------------------------------------------------------
// Function: H5Location::flush
///\brief Flushes all buffers associated with a location to disk.
///\param scope - IN: Specifies the scope of the flushing action,
/// which can be either of these values:
/// \li \c H5F_SCOPE_GLOBAL - Flushes the entire virtual file
/// \li \c H5F_SCOPE_LOCAL - Flushes only the specified file
///\exception H5::Exception
///\par Description
/// This location is used to identify the file to be flushed.
// Programmer Binh-Minh Ribler - 2012
// Modification
// Sep 2012 - BMR
// Moved from H5File/H5Object
//--------------------------------------------------------------------------
void H5Location::flush(H5F_scope_t scope) const
{
herr_t ret_value = H5Fflush(getId(), scope);
if( ret_value < 0 )
{
throw LocationException(inMemFunc("flush"), "H5Fflush failed");
}
}
//--------------------------------------------------------------------------
// Function: H5Location::getComment
///\brief Returns the comment as \a string for this location,
/// returning its length.
///\param name - IN: Name of the object
///\param buf_size - IN: Length of the comment to retrieve, default to 0
///\return Comment string
///\exception H5::LocationException
// Programmer Binh-Minh Ribler - 2000 (moved from CommonFG, Sep 2013)
//--------------------------------------------------------------------------
H5std_string H5Location::getComment(const char* name, size_t buf_size) const
{
// Initialize string to "", so that if there is no comment, the returned
// string will be empty
H5std_string comment("");
// Preliminary call to get the comment's length
ssize_t comment_len = H5Oget_comment_by_name(getId(), name, NULL, (size_t)0, H5P_DEFAULT);
// If H5Oget_comment_by_name returns a negative value, raise an exception
if (comment_len < 0)
{
throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
}
// If comment exists, calls C routine again to get it
else if (comment_len > 0)
{
size_t tmp_len = buf_size;
// If buffer size is not provided, use comment length
if (tmp_len == 0)
tmp_len = comment_len;
// Temporary buffer for char* comment
char* comment_C = new char[tmp_len+1];
HDmemset(comment_C, 0, tmp_len+1); // clear buffer
// Used overloaded function
ssize_t comment_len = getComment(name, tmp_len+1, comment_C);
if (comment_len < 0)
{
delete []comment_C;
throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
}
// Convert the C comment to return
comment = comment_C;
// Clean up resource
delete []comment_C;
}
// Return the string comment
return(comment);
}
//--------------------------------------------------------------------------
// Function: H5Location::getComment
///\brief Retrieves the comment for this location, returning its length.
///\param name - IN: Name of the object
///\param buf_size - IN: Length of the comment to retrieve
///\param comment - OUT: Retrieved comment
///\return Actual length of the comment
///\exception H5::LocationException
///\par Description
/// This function retrieves \a buf_size characters of the comment
/// including the null terminator. Thus, if the actual length
/// of the comment is more than buf_size-1, the retrieved comment
/// will be truncated to accommodate the null terminator.
// Programmer Binh-Minh Ribler - Mar 2014
//--------------------------------------------------------------------------
ssize_t H5Location::getComment(const char* name, size_t buf_size, char* comment) const
{
// H5Oget_comment_by_name will get buf_size chars of the comment including
// the null terminator
ssize_t comment_len;
comment_len = H5Oget_comment_by_name(getId(), name, comment, buf_size, H5P_DEFAULT);
// If H5Oget_comment_by_name returns a negative value, raise an exception
if (comment_len < 0)
{
throw LocationException("H5Location::getComment", "H5Oget_comment_by_name failed");
}
// If the comment is longer than the provided buffer size, the C library
// will not null terminate it
if ((size_t)comment_len >= buf_size)
comment[buf_size-1] = '\0';
// Return the actual comment length, which might be different from buf_size
return(comment_len);
}
//--------------------------------------------------------------------------
// Function: H5Location::removeComment
///\brief Removes the comment from an object specified by its name.
///\param name - IN: Name of the object
///\exception H5::LocationException
// Programmer Binh-Minh Ribler - May 2005 (moved from CommonFG, Sep 2013)
// 2007: QAK modified to use H5O APIs; however the first parameter is
// no longer just file or group, this function should be moved
// to another class to accommodate attribute, dataset, and named
// datatype. - BMR
//--------------------------------------------------------------------------
void H5Location::removeComment(const char* name) const
{
herr_t ret_value = H5Oset_comment_by_name(getId(), name, NULL, H5P_DEFAULT);
if( ret_value < 0 )
throw LocationException(inMemFunc("removeComment"), "H5Oset_comment_by_name failed");
}
//--------------------------------------------------------------------------
// Function: H5Location::setComment
///\brief This is an overloaded member function, provided for convenience.
/// It differs from the above function in that it doesn't take
/// an object name.
// Programmer Binh-Minh Ribler - Sep 2013
// Modification
//--------------------------------------------------------------------------
void H5Location::setComment(const char* comment) const
{
herr_t ret_value = H5Oset_comment_by_name(getId(), ".", comment, H5P_DEFAULT);
if( ret_value < 0 )
throw LocationException(inMemFunc("setComment"), "H5Oset_comment_by_name failed");
}
