Functions

The length of the title of the table.

The title returned here is the complete title as displayed over the table.

The user may change the composition of the title, but the standard template is "&o&dTable 1&v&s", which means that the table shows:

• The organisation.
• The database.
• The phrase "Table 1".
• The list of fields making up the table.
• The list of values making up the subject population.

See QueryPartTitleTable() below for a complete list of template entries.

The length of the footnotes of the table.

The footnotes returned here are the complete list of footnotes displayed below the table.

The user may change the composition of the footnotes, but the standard template is "&r&f&c&p", which means that the footnotes contain:

• A string describing the randomisation applied to the table.
• All of the footnotes supplied from the database.
• All footnotes attached to derivations.
• Descriptions of power of ten formatting used on the cell data.

The length of the text in the buffer. Valid template strings are:

The number of fields in the nominated axis. There are four axes (including the subject population), and there may be zero or more fields in each. Each field dimension in the table is in exactly one axis.

The length of the code of the field (up to 8 chars, all uppercase). This code is the identifier for the field. It may only contain uppercase alphanumeric characters; it will not contain spaces.

The length of the footnotes relating to the field. This provides the footnotes associated with the field in the database.

The length of the timestamp for the field (a string in the format "YYYYmmddhhmmss").

• The timestamp for a user defined field is the timestamp when the user pressed OK on defining or editing the user defined field.
• The timestamp for a recoded field is the timestamp when the user pressed OK on defining or editing the recode. A recode that is saved to a file and reloaded will retain the timestamp from when it was defined (loading a recode from a file does not change its timestamp).

The length of the name of a value in a field. This name is the name that is displayed on the table, providing the user did not select the Codes option in the
Define Recode dialog. The name is a text string and may contain spaces.

This function applies to a specific point in a field as displayed, not a natural value.

The length of the code of a value in a field. This code is the code that is displayed in the table if the user selected Codes in the Define Recode dialog. The code is a short string that does not contain spaces.

This function applies to a specific point in a field as displayed, not a natural value.

The length of the unique code of a value in a field

The unique codes are normally numeric. They are guaranteed to be unique within a field, even if the field is hierarchical. They are especially useful for area fields, where areas at different levels in the hierarchy may have the same code, returned by QCodeValueOPROC(), they will have different codes returned by this function. This function applies to a specific point in a field as displayed, not a natural value.

Whether the nominated natural value in the field is hidden. This function applies to a specific value in the field, not a displayed entry.

The natural value at a specific point in the field as displayed. If the point nominated is not natural this function returns a negative number.

The type of value at a specified point in a field. This function applies to a specific point in a field as displayed, not a natural value.

The level on the axis at which a nominated field lies.

The level of a field on an axis is a number. Considering column headings, the level 0 field is at the top. The level 1 field is immediately under the level 0, and so forth.

TRUE if successful, FALSE if not.

This function accesses the data by field value. It does not access the table as displayed.

Axis derivations and arrangements are not accessible using this function.

TRUE if there is another non zero cell, FALSE if there is not.

The caller initializes the index array and calls this routine, which updates the array to hold the index of the next non zero cell. This routine moves through the table field by field, enumerating all of the values in the last field before moving through the second-last field. Putting this another way, index[0] changes least often. If the index array is initialized to all zeros, and this function called repeatedly, all non zero cells (except 0, 0, 0...) of the table will be traversed. The caller is responsible for determining if the first cell (0, 0, 0...) is non zero, which can be done by calling QueryDataCellIndex().

The number of entries in an axis. This is not necessarily the same as the product of the number of entries in each field on the axis. The user may add axis derivations, and may hide values.

The number of natural entries in an axis. This is the product of the sizes of the fields in the axis, not the product of the numbers of natural values in the fields. Field derivations are considered natural values for axes.

The length of the name of the entry at the specified point in the axis.

The name of an entry is obtained in one of two ways: if the entry is an axis derivation, then the name is the name of that axis derivation; if the entry is not an axis derivation, then the name is the concatenation of the names of the component entries for each field. If this name is composed from different fields, entries from different fields are separated by a comma followed by a blank space.

The length of the name of the entry at the specified point in the axis.

The name of an entry is obtained in one of two ways: if the entry is an axis derivation, then the name is the name of that axis derivation; if the entry is not an axis derivation, then the name is the concatenation of the names of the component entries for each field.

If this name is composed from different fields, the entries are separated by a comma followed by a blank space.

The type of entry at a specified point on a nominated axis.

There are three possible results from this function. The nominated entry may be an axis derivation (kAxisDerivation). If it is not, it may be composed strictly of natural values from each of the fields on this axis (kNatural). If any of the fields contributes a field derivation rather than a natural value, then kFieldDerivation is returned.

The natural value at a specific point in the axis as displayed. If the point nominated is not a natural value this function returns a negative number.

The index in the field of a specified point on an axis.

This function allows a point on an axis to be decomposed into its component field entries. A natural axis value will yield anon-negative index.

The return value of this function is not defined when the EntryNum specifies an axis derivation (this function should not be called if QueryEntryTypeAxis() returns kAxisDerivation for this entry). The axis is implicit; each field is on exactly one axis, so specifying the field number specifies the axis.

The length of the expression for a nominated axis derivation.

For more information on on the format of derivations, see Derivations.

The return value of this function will be zero if EntryNum does not specify an axis derivation.

TRUE if successful, FALSE if not.

This accesses the data by wafer, row, and column, accessing the table as displayed, including derivations and rearrangements. Hidden values are not accessible using this function.

TRUE if there is another non zero cell, FALSE if there is not.

The caller initializes the index array and calls this routine which updates the array to hold the index of the next non zero cell. This routine moves through the table by column, then row, then wafer. If the index array is initialized to all zeros, and this function called repeatedly, all non zero cells (except 0, 0, 0) of the table will be traversed. The caller is responsible for determining if the first cell (0, 0, 0) is non zero, which can be done by calling QueryDataCellAxis().

Length of the TextBuff (Annotation text in the cell).

Copies the text for the nominated annotation into TextBuff if it is not null and if LenBuff is greater than zero. This function will truncate the text to the number of characters indicated by LenBuff.

If TextBuff is null or LenBuff is zero, then this function will simply return the length of the annotation text.

TRUE if the nominated cell has the nominated annotation, FALSE if not.

This accesses the cell annotation by field value. This does not access the table as displayed. Axis derivations and arrangements are not accessible using this function.

TRUE if the nominated cell has the nominated annotation, FALSE if not.

Determine if a cell, nominated by its axis index, has a particular annotation. This accesses the data by wafer, row, and column, as displayed (including derivations and rearrangements). Hidden values are not accessible using this function.

TRUE if it is a derived value, FALSE otherwise. This function applies to a specific point in a field as displayed, not a natural value.

The length of the recode ID text. This function copies the ID of the nominated recode in to IDBuff if it is not null and if LenBuff is greater than zero.

This function will truncate the ID to the number of characters specified by LenBuff. If IDBuff is null or LenBuff is zero, then this function will simply return the length of the recode ID.

The length of the Base field ID text. This function copies the ID of the Recode's Base Field (the field the recode is based on) into IDBuff, if it is not null and if LenBuff is greater than zero. This function will truncate the ID to the number of characters specified by LenBuff.

If IDBuff is null or LenBuff is zero, then this function will simply return the length of the recode ID.

The number of values for the given recode. This function copies the value numbers for each of the values in the field dimension belonging to this recode into the values array up to NumVals.

If values is null or numVals is zero, then this function will simply return the number of values in this recode.

The length of the Recode ID text. This function copies the value numbers for each of the values making up the given recode total into the values array up to numVals. If Values is null or NumVals is zero then this function simply returns the number of values making up this total.

The length of the Recode Name text (not including the terminating '\0').

This function copies the name of the nominated recode into NameBuff if it is not null and if LenBuff is greater than zero. This function will truncate the ID to the number of characters specified by LenBuff. If NameBuff is null or LenBuff is zero, then this function will simply return the length of the recode name.

If this is the only recode in the field dimension (that is, not recode/field concatenation), this should return the same name as the field dimension name.

TRUE if the ID was set successful, else FALSE.

If it is not null and if LenBuff is greater than zero, this function will truncate the ID to the number of characters specified by LenBuff. If IDBuff is null or LenBuff is zero, then this function will simply return the length of the recode ID.

Length of the text copied into TextBuff (including the terminating '\0').

This function copies the text for the nominated footnote into TextBuff if it is not null and if LenBuff is greater than zero. This function will truncate the text to the number of characters indicated by LenBuff. If TextBuff is null or LenBuff is zero, then this function will simply return the length of the footnote text.

This function applies to a specific point in a field as displayed, not a natural value.

Get the data at a particular point in the table (indexed by field value) with special string. This function is same as QueryDataCellIndex() except that it also gets any special string displayed in this cell, such as zero values or ...C for confidential values.

Use this function if you need to know whether the cells are confidential, not applicable or blank. If you just need the real value, use QueryDataCellIndex(). If SpecialString is NULL or maxlen is 0, this function will behave exactly the same way as QueryDataCellIndex().

TRUE if successful, FALSE if not.

This accesses the data by field value. This does not access the table as displayed. Axis derivations and arrangements are not accessible using this function.

Get the data value for a particular cell in the table with special string. This function is same as QueryDataCellAxis() except that it also gets any special string displayed in this cell, such as zero values or ...C for confidential values. Use this function if you need to know whether the cells are confidential, not applicable or blank. If you just need the real value, use QueryDataCellAxis().

If SpecialString is NULL or maxlen is 0, this function will behave exactly the same way as QueryDataCellIndex().

TRUE if successful, FALSE if not.

This function accesses the data by wafer, row, and column. It accesses the table as displayed, including derivations and rearrangements. Hidden values are not accessible using this function.

The number of decimal places.

This function accesses the data by wafer, row, and column. It accesses the table as displayed, including derivations and rearrangements. Hidden values are not accessible using this function.

The number of values making up this derived sum. If Values is not NULL and NumValues is not zero, and if the actual number of values making up the derivation total is higher than NumValues, it simply returns NumValues.

Determine if this axis item contains an axis or field derivation of the given type.

This function is built up of QueryEntryTypeAxis(), QueryDerivationKindAxis() and QueryDerivationKindField(). It is used in conjunction with QueryEntryTypeAxis() to avoid having to get loop through all the field items to see what type of derivation we are dealing with.

Returns the number of non zero cells that can be accessed via the field index. Some cells not accessible via the axis index are accessible via the field index due to the axis item been hidden. Hidden field items are not accessible

Gets the field index of the first non zero cell.

You should be certain that there is a least one non zero cell before calling this function. You can check this using the function QueryNumNonZeroCellsFieldIndex(). You should also sort the list according to the field order specified in the sort order array.

Gets the field index of the next non zero cell.

The first non zero field index should be found using the function QueryFirstNonZeroCellFieldIndex(). Each successive call to QueryNextNonZeroCellFieldIndex() will then retrieve the next non zero field index until there are no more cells to be retrieved, at which point this function will return 0.

Returns TRUE if there are more non zero cells to follow, FALSE if this is the last or -1 if an error occurred.

When this function returns FALSE, it indicates that there are no more to follow, but the index it returned with is a valid one and it should be processed.

Whether or not this table has any summation fields specified.

• If this function returns FALSE, then QueryFieldRecodeSummations() will always return FALSE.
• If this function returns TRUE, then QueryFieldRecodeSummations() will return TRUE once.

The axis index of the auto axis-total item or -1 if there is no axis item.

This function is guaranteed to return kAxisDerivation from QueryEntryTypeAxis() and TRUE from QueryIsSumDerivationValue().

A structure filled with the alignment information for the table's header, footer, rows, columns and wafers, and also the vertical alignment of the row.

Possible horizontal settings are: left, right or center, and possible vertical settings are: top, bottom or center.

Size in bytes of the MetaDataInfo->Info string:

• 0 if there is no TextMetaData.
• -1 if there is an error.

If 0 is returned, it is probable the text MetaData is a link; check MetaDataInfo>Type to confirm.

Size in bytes of the MetaDataInfo->Info string:

• 0 if there is no TextMetaData.
• -1 if there is an error.

If 0 is returned, it is probable the text MetaData is a link; check MetaDataInfo>Type to confirm.

Size in bytes of the MetaDataInfo->Info string:

• 0 if there is no TextMetaData.
• -1 if there is an error.

If 0 is returned, it is probable the text MetaData is a link; check MetaDataInfo>Type to confirm.

The large axis mode of the axis:

• 0 if the axis is not in a large axis mode.
• 1 if the axis is in a large axis mode with values not revealed.
• 2 if the axis is in a large axis mode with the values revealed.

This name is the name that is displayed on the table, providing the user did not select Codes in the Define Recode dialog. This name is a text string which may contain spaces. This function applies to a specific point in a field as displayed, not a natural value.

The rounding method associated with the database. Possible return values are:

• kConfid_Not-Set
• kConfid_None
• kConfid_0to3
• kConfid_Mod3
• kConfid_1to4
• kConfid_Grad
• kConfid_NoDisplay

TRUE if is confidential, FALSE if not.

This function accesses the data by field value; it does not access the table as displayed. Axis derivations and arrangements are not accessible using this function.

Length of the annotation footnote text.

This function copies the footnote for the nominated annotation into TextBuff if it is not null and if LenBuff is greater than zero.

This function will truncate the text to the number of characters indicated by LenBuff.

If TextBuff is null or LenBuff is zero, then this function will simply return the length of the annotation footnote text.

Length of the TextBuff. Copies the text for the nominated standard annotation into TextBuff if it is not null and if LenBuff is greater than zero. This function will truncate the text to the number of characters indicated by LenBuff.

If TextBuff is null or LenBuff is zero, then this function will simply return the length of the annotation text.

Length of the TextBuff. Copies the footnote for the nominated standard annotation in to TextBuff if it is not null and if LenBuff is greater than zero. This function will truncate the text to the number of characters indicated by LenBuff.

If TextBuff is null or LenBuff is zero, then this function will simply return the length of the annotation footnote text.

The length of the name of the entry at the specified point in the axis.

The name of an entry is obtained in one of two ways: if the entry is an axis derivation, then the name is the name of that axis derivation; if the entry is not an axis derivation, then the name is the concatenation of the names of the component entries for each field.

If this name is composed of entires from different fields, they are separated by a comma followed by a blank space.

The number of contributors to the specified cell or -1 on failure.

This will return -1 if used in a table where the number of contributors is not used for any confid methods in the table because in this case the hDSNumContribs datastore will not exist.

The number of contributors to the specified cell or -1 on failure.

This will return -1 if used in a table where the number of contributors is not used for any confid methods in the table because in this case the hDSNumContribs datastore will not exist.

TRUE on success FALSE on failure.

The values of the top contributors for the specified cell are copied into the provided contributions buffer. The caller must allocate and free the contributions buffer.

If the number of contributors to the specified cell are less than or equal to the number of values to be stored for the rule, the results will be zero.

TRUE on success FALSE on failure.

The values of the top contributors for the specified cell are copied into the provided contributions buffer. The caller must allocate and free the contributions buffer.

If the number of contributors to the cell specified are less than or equal to the number of values to be stored for the rule, the results will be zero.

The length of the name of the entry at the specified point in the axis

The name of an entry is obtained in one of two ways:

• If the entry is an axis derivation, then the name is the name of that axis derivation.
• If the entry is not an axis derivation, then the name is the concatenation of the names of the component entries for each field.

If this name is composed from different fields, the entries are separated by newline characters. This function is an extension in that there are a series of flags that can be used to define how the string is formatted.

The number of table languages available, or:

• 0 - the database is not multilingual.
• -1 - there was an error.

Get the field IDs of all the parent values in the supplied hierachical field.

You can use QueryUniqueValue() to retrieve a field's ID in order to recognise the parent if it is on the table. QueryParentValue() can also be used to retrieve only the immediate parent.

If ancestors is NULL or ancestorSize is less then 1, then only the number of ancestors is returned.