NAME

       gd_move — move a Dirfile entry between format specification fragments

SYNOPSIS

       #include <getdata.h>

       int gd_move(DIRFILE *dirfile, const char *field_code, int new_fragment, unsigned int
              flags);

DESCRIPTION

       The gd_move() function transfers the field or alias specified by field_code, which  should
       not  have  a  representation suffix, defined in the dirfile specified by dirfile from it's
       current format specification fragment to the fragment indexed  by  new_fragment.   If  the
       field is already defined in the fragment index by new_fragment, this function does nothing
       and returns no error.

       If the new fragment has different affixes, the field will be renamed as part of the  move.
       See  gd_rename(3)  for  details  on  field  renaming.   The field is closed before moving,
       resulting in it's I/O pointer being reset to the beginning-of-field.

       The flags parameter should be zero or more of the following flags, bitwise or'd together:

       GD_REN_DANGLE
               By default, if the move results in a change of name for the field due to differing
               fragment  affixes,  ALIAS  entries pointing to this field will be updated with the
               field's new name.  Specifying this flag prohibits this  behaviour,  turning  these
               aliases  into  dangling aliases.  If moving the field doesn't rename it, this flag
               is ignored.

       GD_REN_DATA
               If field_code specifies a RAW field, the binary file  associated  with  the  field
               will be translated to account for the possibly different encoding, endianness, and
               frame offset of the new format specification fragment.  It will also be moved to a
               new directory, if necessary.

               If  this  flag  is  not specified, no changes will be made to the binary file.  If
               field_code specifies a field of type other than RAW, this flag is ignored.

               If the binary file is translated, and the frame offset of the destination fragment
               is larger than that of the source fragment, this will result in permanent deletion
               of data from the database.  If the new frame offset is smaller than the old  frame
               offset, the binary file will be padded at the front with zeroes.

       GD_REN_FORCE
               Skip  updating  entries which would be invalid (see gd_rename(3) for details).  By
               default, an invalid field causes the move to fail.  If moving  the  field  doesn't
               rename it, this flag is ignored.

       GD_REN_UPDB
               If moving the field renames it, update entries which use this field as an input to
               account for the new name (see gd_rename(3)).  If moving the field  doesn't  rename
               it, this flag is ignored.

RETURN VALUE

       On  success, gd_move() returns zero.   On error, a negative-valued error code is returned.
       Possible error codes are:

       GD_E_ACCMODE
               The specified dirfile was opened read-only.

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The field specified by field_code was not found, or else the move resulted in  the
               field being renamed and the resultant metadata update tried to change a field code
               into something prohibited by a fragment's affixes.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_FIELD_TYPE
               An attempt was made to move the immutable INDEX field.

       GD_E_BAD_INDEX
               The new_fragment argument did not index a valid format specification fragment.

       GD_E_IO An I/O error occurred while attempting to translate a binary file.

       GD_E_PROTECTED
               The metadata of the source  or  destination  format  specification  fragments  was
               protected  from  change, or the binary data of the source or destination fragments
               was protected from change and binary file translation was requested.

       GD_E_UNKNOWN_ENCODING
               The encoding scheme of the source or destination fragment is unknown.

       GD_E_UNSUPPORTED
               The encoding scheme of the source or destination fragment does not support  binary
               file translation.

       The  error  code  is  also  stored  in  the DIRFILE object and may be retrieved after this
       function returns by calling gd_error(3).  A descriptive error string for the error may  be
       obtained by calling gd_error_string(3).

NOTES

       A  binary  file  translation  occurs  out-of-place.  As a result, sufficient space must be
       present on the filesystem for both the binary file before translation and the binary  file
       after translation.

HISTORY

       The  dirfile_move()  function  appeared  in GetData-0.5.0.  It had no flags parameter.  In
       place of flags was int move_data.  Passing a non-zero value for  this  parameter  had  the
       same effect as the GD_REN_DATA flag does now.

       In GetData-0.7.0, this function was renamed to gd_move().

       In  all  GetData-0.8.x  releases,  passing  an  alias name to this function would move the
       target of the alias.  To move an alias itself, a separate  function,  gd_move_alias()  was
       available.

       In  GetData-0.9.0,  gd_move_alias()  was  removed.   Also  in  this release, the move_data
       parameter was repaced with the flags parameter.

       In GetData-0.10.0, the error return from this function changed  from  -1  to  a  negative-
       valued error code.

SEE ALSO

       gd_metaflush(3),   gd_open(3),   gd_error(3),   gd_error_string(3),  dirfile(5),  dirfile-
       format(5)