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, -1 is returned and the dirfile error is set
       to a non-zero error value.  Possible error values 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 dirfile error may be retrieved by calling gd_error(3).  A descriptive error string for
       the last error encountered can be obtained from a call to 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.

SEE ALSO

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