.\" header.tmac. GetData manual macros. .\" .\" Copyright (C) 2016 D. V. Wiebe .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" .\" This file is part of the GetData project. .\" .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.2 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover .\" Texts. A copy of the license is included in the `COPYING.DOC' file .\" as part of this distribution. .\" Format a function name with optional trailer: func_name()trailer .de FN \" func_name [trailer] .nh .BR \\$1 ()\\$2 .hy .. .\" Format a reference to section 3 of the manual: name(3)trailer .de F3 \" func_name [trailer] .nh .BR \\$1 (3)\\$2 .hy .. .\" Format the header of a list of definitons .de DD \" name alt... .ie "\\$2"" \{ \ .TP 8 .PD .B \\$1 \} .el \{ \ .PP .B \\$1 .PD 0 .DD \\$2 \\$3 \} .. .\" Start a code block: Note: groff defines an undocumented .SC for .\" Bell Labs man legacy reasons. .de SC .fam C .na .nh .. .\" End a code block .de EC .hy .ad .fam .. .\" Format a structure pointer member: struct->member\fRtrailer .de SPM \" struct member trailer .nh .ie "\\$3"" .IB \\$1 ->\: \\$2 .el .IB \\$1 ->\: \\$2\fR\\$3 .hy .. .\" Format a function argument .de ARG \" name trailer .nh .ie "\\$2"" .I \\$1 .el .IR \\$1 \\$2 .hy .. .\" Hyphenation exceptions .hw sarray carray lincom linterp .\" gd_alter_entry.3. The gd_alter_entry man page. .\" .\" Copyright (C) 2008, 2009, 2010, 2012, 2013, 2014, 2016 D. V. Wiebe .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" .\" This file is part of the GetData project. .\" .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.2 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover .\" Texts. A copy of the license is included in the `COPYING.DOC' file .\" as part of this distribution. .\" .TH gd_alter_entry 3 "25 December 2016" "Version 0.10.0" "GETDATA" .SH NAME gd_alter_entry \(em modify the metadata of a Dirfile field .SH SYNOPSIS .SC .B #include .HP .BI "int gd_alter_entry(DIRFILE *" dirfile ", const char *" field_code , .BI "const gd_entry_t *" entry ", int " recode ); .EC .SH DESCRIPTION The .FN gd_alter_entry function modifies the field specified by .ARG field_code in the dirfile specified by .ARG dirfile to correspond to the new parameters specified by .ARG entry . In addition to specifying a regular field, .ARG field_code may also refer to a metafield by specifying it using its full (slashed) field code. However, .ARG field_code should never contain a representation suffix. The form of .ARG entry is described in detail in the .F3 get_entry man page. The .SPM entry field and .SPM entry fragment_index members are ignored by this function and need not be initialised. All other members appropriate to the field type of .ARG field_code should be initialised, except as noted below. To change the fragment index of a field, use .F3 gd_move . To change the name of a field, use .F3 gd_rename . The only flags in the .SPM entry flags member which are honoured are .BR GD_EN_HIDDEN , which should be set or cleared to set the hiddenness of the entry (see .F3 gd_hidden ), and .BR GD_EN_COMPSCAL , which indicates whether scalar parameters are initialised from the complex valued or purely real member, which both are present .RB ( LINCOM , .BR POLYNOM , .BR RECIP ). If .ARG field_code specifies a .B RAW field and the .ARG recode argument is non-zero, the binary file associated with the field will be converted for changes in data type and samples-per-frame. In this case, the field's I/O pointer will be reset to the beginning-of-frame. If .ARG recode is zero, no binary file conversion will take place. If .ARG field_code specifies a .B LINTERP field and the .ARG recode argument is non-zero, the look-up table file will be moved if .SPM entry table specifies a different path. If a file with the new pathname already exists, it will be overwritten. If the field specified by .ARG field_code is of type other than .B RAW or .BR LINTERP , the .ARG recode argument is ignored. If .ARG field_code specified a .B LINCOM or .B POLYNOM field, the value of .SPM entry comp_scal indicates whether the purely real scalar lists .RI ( entry -> a ", or " entry -> b " and " entry -> m ) or the complex valued lists .RI ( entry -> ca ", or " entry -> cb " and " entry -> cm ) will be used. The unused counterparts need not be initialised. The .SPM entry field_type member must correspond to the field type of .ARG field_code . This interface cannot be used to change the type of a given field. To do so, delete the old field first with .F3 gd_delete , and then create a new field of the desired type with .F3 gd_add . Some entry members have special values which indicate no change should be made to the member. These special values are: .DD NULL\fR: any of the string members; .DD 0\fR: .IR spf ", " n_fields ", " numbits ", " cdividend ", " dividend ", or " array_len ; .DD -1\fR: .IR bitnum " or " period ; .DD GD_NULL\fR: .IR data_type " or " const_type ; .DD GD_WINDOP_UNK\fR: .IR windop . .PP All .SPM entry scalar elements relevant for the given field type must be initialised to one of the following values: .IP \(bu 4 a pointer to a field code indicating a new scalar field to be used for the corresponding field parameter. If the parameter was previously a literal number, it will be replaced by the specified field code. If the parameter was previously a field code, the new field code will replace the old one. If the field code specifies a .B CARRAY field, the corresponding .SPM entry scalar_ind element should also be set. .IP \(bu 4 a pointer to the empty string (""). In this case, no change is made to the field code for the corresponding field parameter: if one already existed, it is kept, otherwise the corresponding literal numerical parameter is used. If the value of the corresponding numerical .ARG entry member is the special value listed above indicating no change, no change is made to the field parameter at all. .B NB: In this case, GetData also ignores the corresponding .SPM entry scalar_ind element, even if it differs from the current value. To change a .ARG scalar_ind element without changing the corresponding .ARG scalar , set that .ARG scalar element to its current value (at which point GetData operates as per the previous bullet). .IP \(bu 4 the NULL pointer. If the corresponding field parameter was previously a field code, the field code will be deleted and a literal number used instead. In the special case when a scalar element is NULL and the corresponding numerical .ARG entry member contains a special value indicating no change listed above, GetData will de-reference the previous field code value and convert it into a literal number before removing the field code from the entry. .PP If this function is used to increase the length of a .B CARRAY field, the added elements will be uninitialised. Use .F3 gd_put_carray_slice or equivalent to initialise them. .SH RETURN VALUE On success, .FN gd_alter_entry return zero. On error, a negative-valued error code is returned. Possible error codes are: .DD GD_E_ACCMODE The specified dirfile was opened read-only. .DD GD_E_ALLOC The library was unable to allocate memory. .DD GD_E_BAD_CODE The field specified by .ARG field_code was not found or a supplied field code did not contain the appropriate prefix or suffix. This error may also result from attempting to dereference a scalar field code which indicates a non-existent field. .DD GD_E_BAD_DIRFILE The supplied dirfile was invalid. .DD GD_E_BAD_ENTRY One or more of the parameters specified in .ARG entry was invalid. .DD GD_E_BAD_FIELD_TYPE The .SPM entry field_type parameter did not correspond to the type of the field specified by .ARG field_code , or an attempt was made to modify the immutable .I INDEX field. This error may also result from attempting to dereference a scalar field code which does not indicate a .B CONST or .B CARRAY field. .DD GD_E_BAD_TYPE The .SPM entry data_type parameter provided with a .BR RAW entry, or the .SPM entry const_type parameter provided with a .BR CONST or .BR CARRAY entry, was invalid. .DD GD_E_IO An I/O error occurred while translating the binary file associated with a modified .B RAW field, or an I/O error occurred while attempting to rename a .B LINTERP table file. .DD GD_E_PROTECTED The metadata of the fragment was protected from change. Or, a request to translate the binary file associated with a .B RAW field was attempted, but the data of the fragment was protected. .DD GD_E_UNKNOWN_ENCODING The encoding scheme of the indicated format specification fragment is not known to the library. As a result, the library was unable to translate the binary file be associated with a modified .B RAW field. .DD GD_E_UNSUPPORTED The encoding scheme of the indicated format specification fragment does not support translating the binary file associated with a modified .B RAW field. .PP The error code is also stored in the .B DIRFILE object and may be retrieved after this function returns by calling .F3 gd_error . A descriptive error string for the error may be obtained by calling .F3 gd_error_string . .SH HISTORY The function .FN dirfile_alter_entry appeared in GetData-0.5.0. In GetData-0.7.0, this function was renamed to .FN gd_alter_entry . In GetData-0.8.0, the first version supporting fragment affixes, this function would apply the destination fragment's affixes to the supplied .SC .SPM entry field .EC name. In GetData-0.8.1, this changed: .FN gd_alter_entry now assumes .SC .SPM entry field .EC contains the full field name, including any necessary affixes. In GetData-0.10.0, the error return changed from -1 to a negative-valued error code. See .F3 gd_entry for the history of the .B gd_entry_t structure. .SH SEE ALSO .F3 gd_alter_bit , .F3 gd_alter_carray , .F3 gd_alter_const , .F3 gd_alter_divide , .F3 gd_alter_lincom , .F3 gd_alter_linterp , .F3 gd_alter_multiply , .F3 gd_alter_phase , .F3 gd_alter_polynom , .F3 gd_alter_raw , .F3 gd_alter_recip , .F3 gd_alter_spec , .F3 gd_delete , .F3 gd_error , .F3 gd_error_string , .F3 gd_hidden , .F3 gd_malter_spec , .F3 gd_metaflush , .F3 gd_move , .F3 gd_open , .F3 gd_put_carray_slice , .F3 gd_rename , dirfile-format(5)