The IB_XMLDA Structure

Go Up to Using the InterBase API to Generate XML

The IB_XMLDA structure is contained in the ibxml.h file. It looks like this:

typedef struct ib_xmlda {
char ISC_FAR *xmlda_file_name; /* Points to a char string containing
the name of the file used by xml_fetch();
ignored by the buffer function */
char ISC_FAR *xmlda_header_tag; /* Points to the string which is printed
out as the header tag */
char ISC_FAR *xmlda_database_tag; /* Points to the string that is printed
out as the database tag in the xml file*/
char ISC_FAR *xmlda_table_tag; /* Points to the string that is printed
out as the tablename tag in the
xml file */
char ISC_FAR *xmlda_row_tag; /* Points to the string that is printed
out as the rowname tag in the xml file */
FILE *xmlda_file_ptr; /* Used internally by the API to hold the file pointer; can be POINTER type in non-C, C++ programs */ char ISC_FAR **xmlda_temp_buffer; /* Internal use only, used for storing the string array from fetch() */
ISC_STATUS xmlda_fetch_stat; /* Holds the return value from the
isc_dsql_fetch() call; it indicates whether all the records have been redeived or if there is an error */
ULONG xmlda_flags; /* Flags explained below */
ULONG xmlda_more_data; /* Used by the buffer call to maintain the
status of the last record: 0 if there is no more data, 1 if there is data that has been fetched but not put out in the buffer */
ISC_ULONG xmlda_temp_size; /* Internal use only, stores the size of
the last record */
ISC_USHORT xmlda_status; /* Internal status must be set to 0 by user
when called for the first time */
USHORT xmlda_more; /* Used in conjunction with the buffered
mode; set this if there is more XML data */
USHORT xmlda_version; /* Version of XMLDA */
USHORT xmlda_array_size; /* Internal use only */
SLONG xmlda_reserved; /* Reserved for future use */
} IB_XMLDA;

Required Elements of the IB_XMLDA Structure

Before calling any of the three XML functions, you must set the following elements of the IB_XMLDA structure:

1. xmlda_file_name is the name, including complete path, of the file to which the XML output should be written. Only isc_dsql_xml_fetch() and isc_dsql_xml_fetch_all() require this name.
2. xmlda_version should be set to 1, indicating that the parser should use the XSQLDA descriptor area, rather than the older SQLDA descriptor area.
3. xmlda_status should be set to zero the first time isc_dsql_xml_fetch() is called. It does not have any effect in isc_dsql_fetch_all(), but it is recommended that you set it to zero. It is used internally by the XML functions to keep status.

Optional Elements of the IB_XMLDA Structure

1. xmlda_header_tag points to a character string to be used as the XML header. If this is set to NULL, it prints the default header, <?xml version="1.0">.
2. xmlda_database_tag points to a character string that can be used in place of the Database tag. (See example XML document below.) If this is set to NULL, the XML tag defaults to “Database”.
3. xmlda_table_tag points to a character string that can be used in place of the Tablename tag. (See example XML document below.) If this is set to NULL, the XML tag defaults to “Tablename”.
4. xmlda_row_tag points to a character string that can be used in place of the Row tag. (See example XML document below.) If this is set to NULL, the XML tag defaults to “Row”.
5. xmlda_flags currently has two allowable values:
   • XMLDA_ATTRIBUTE_FLAG generates the XML document as attributes instead of as tags
   • XMLDA_NO_NULL_DISPLAY_FLAG does not display the null data and the associated tags.
6. xmlda_file_ptr should be assigned to a previously opened FILE pointer. The file is assumed to be open for writing. The function starts writing from the location of the write pointer. You can set or reset the write pointer to a specific location if you wish. It is recommended that you do not modify this FILE structure once it is in use by the function. You are responsible for closing the file.

Defines

There are three defines available in ibxml.h:

• XMLDA_ATTRIBUTE_FLAG outputs the data as attributes when set to 1.

#define XMLDA_ATTRIBUTE_FLAG 0x01

• XMLDA_NO_NULL_DISPLAY_FLAG suppresses the display of null data.

#define XMLDA_NO_NULL_DISPLAY_FLAG 0x02

• XMLDA_NO_HEADER_FLAG suppresses display of additional header.

#define XMLDA_NO_HEADER_FLAG 0x04

XMLDA_ATTRIBUTE_FLAG generates the output as attributes instead of elements. This flag affects only the actual data generated from InterBase as the user can control all the other tags by inputting the desired attribute as tags.

Setting the XMLDA_NULL_NO_DISPLAY_FLAG causes the API to skip generating rows for data that is null. The default behavior is to generate empty strings.

Advance To:

• Using the xmlda_flags