Learning Infranet :-- FLISTS data structure

About flists :-
=========

An flist is the fundamental data structure used in Infranet. Flists (field lists) are containers that hold fields, each of which is a pair of data field name and its value.

Example:

LAST_NAME STR "Tripathi"
FIRST_NAME STR "Dharmesh"
COMPANY STR "IBM Global Services"

Infranet processes can interpret data only in an flist format. The storage manager in the Data Manager (DM) translates the flists to a format that the database can process, and then translates the data from the database into an flist before passing it to the Connection Manager (CM).

Infranet uses flists in these ways:


Storable objects are passed in the form of flists between opcodes or programs that manipulate the storable objects.

Opcodes use flists to pass data between the Infranet applications and the database. For each opcode, an input flist is passed to pcm_op() and the return flist is passed back from this routine.
Contents of an flist
In an flist, you can use any of the Infranet supported data types such as decimals, buffers, arrays, and substructures. Flists can contain any number of fields. You can nest flists to any level; that is, you can place flists within other flists.

For a description of the Infranet data types that you can use in an flist, see Understanding the Infranet Data Types. For a list of the data type abbreviations used in flists, see Flist field data types.

The following example shows a partial input flist for the PCM_OP_CUST_COMMIT_CUSTOMER opcode printed out:

Note [0] after the field type represents the element ID. The numbers 0, 1, 2, and so on at the beginning of each line indicate the nesting level of the field, 0 meaning the top level.


0 PIN_FLD_POID POID [0] 0.0.0.1 /plan 11950 0
0 PIN_FLD_CREATED_T TSTAMP [0] (937336272) 09/14/99 12:11:12
0 PIN_FLD_MOD_T TSTAMP [0] (937336272) 09/14/99 12:11:12
0 PIN_FLD_ACCOUNT_OBJ POID [0] 0.0.0.1 /account -1 0
0 PIN_FLD_DEAL_OBJ POID [0] 0.0.0.0 0 0
0 PIN_FLD_DESCR STR [0] "IP with 10 Free hrs per month"
0 PIN_FLD_NAME STR [0] "Basic"0 PIN_FLD_LIMIT ARRAY [840] allocated 3, used 3
1 PIN_FLD_CREDIT_FLOOR NUM [0] 0.000000
1 PIN_FLD_CREDIT_LIMIT NUM [0] 100.000000
1 PIN_FLD_CREDIT_THRESHOLDS INT [0] 0
0 PIN_FLD_SERVICES ARRAY [0] allocated 4, used 4
1 PIN_FLD_DEAL_OBJ POID [0] 0.0.0.1 /deal 9390 0
1 PIN_FLD_SERVICE_OBJ POID [0] 0.0.0.1 /service/ip -1 0
1 PIN_FLD_LOGIN STR [0] "aac4"
1 PIN_FLD_PASSWD_CLEAR STR [0] "aac4"
0 PIN_FLD_NAMEINFO ARRAY [1] allocated 10, used 10
1 PIN_FLD_CONTACT_TYPE STR [0] "Billing"
1 PIN_FLD_LAST_NAME STR [0] "aac1"
1 PIN_FLD_FIRST_NAME STR [0] "aac1"
1 PIN_FLD_TITLE STR [0] "aac1"
1 PIN_FLD_COMPANY STR [0] "aac1"
1 PIN_FLD_ADDRESS STR [0] "aac1"
1 PIN_FLD_CITY STR [0] "aac1"
1 PIN_FLD_STATE STR [0] "CA"
1 PIN_FLD_ZIP STR [0] "99999"
1 PIN_FLD_COUNTRY STR [0] "USA"
0 PIN_FLD_BILLINFO ARRAY [1] allocated 3, used 3
1 PIN_FLD_ACCESS_CODE1 STR [0] "aac1"
1 PIN_FLD_ACCESS_CODE2 STR [0] "aac1"
1 PIN_FLD_BILL_TYPE ENUM [0] 10001
0 PIN_FLD_ACTGINFO ARRAY [1] allocated 0, used 0
0 PIN_FLD_LOCALES ARRAY [1] allocated 1, used 1
1 PIN_FLD_LOCALE STR [0] "ENU"
...

Flist field data types :-
================

When you include a field in an flist, you must also include an abbreviation of the field's data type. The following table lists the valid Infranet field types and their abbreviations.

Field Type Abbreviation :-
==================

PIN_FLDT_ARRAY :- ARRAY
PIN_FLDT_BINSTR :- BINSTR
PIN_FLDT_BUF :- BUF
PIN_FLDT_DECIMAL:- DECIMAL
PIN_FLDT_ENUM :- ENUM
PIN_FLDT_ERRBUF:- ERR
PIN_FLDT_INT:- INT
PIN_FLDT_POID:- POID
PIN_FLDT_STR:- STR
PIN_FLDT_SUBSTRUCT:- SUBSTRUCT



About creating and using an flist
=========================


You create and manipulate flists with the flist manipulation macros in the PIN library. You can add, remove, and modify fields in an flist by using the flist field manipulation macros. For more information see, Flist Management Macros and Flist Field-handling Macros.

Each opcode has an input and output flist specification. For each opcode you call, you need to create an flist for the data you want to pass in. When you create an input or an output flist for an opcode, follow the flist specifications for the opcode. See the flist specifications in the individual opcode descriptions. For access to opcode descriptions, see PCM Opcode Libraries. Drill down to the opcode you want.

Flists are dynamically allocated data structures. When a field is added to an flist, the field value is either already dynamically allocated in memory or is copied into dynamic memory as it is added.

Important :-You need to destroy the flist you create in your programs by calling PIN_FLIST_DESTROY() to reclaim the memory the flist occupied.




Macros or functions used for creating and managing FLISTs in INFRANET :-
==========================================================


Flist Management Macros
--------------------------------------------------------------------------------


PIN_FLIST_CREATE()

PIN_FLIST_DESTROY()

PIN_FLIST_DESTROY_EX()

PIN_FLIST_COUNT()

PIN_FLIST_COPY()

PIN_FLIST_CONCAT()

PIN_FLIST_SORT()

PIN_FLIST_SORT_REVERSE()

PIN_FLIST_PRINT()

PIN_FLIST_TO_STR()

PIN_STR_TO_FLIST()

PIN_FLIST_TO_XML()


--------------------------------------------------------------------------------

PIN_FLIST_CREATE()
Description
This Infranet macro creates an flist which is used to pass parameters to the PCM_OP() function. This routine creates an flist, and returns a pointer that is used to reference the flist by all future operations. All memory for the flist is dynamically allocated.

Synopsis
#include "pcm.h" pin_flist_t * PIN_FLIST_CREATE(ebufp) pin_errbuf_t *ebufp;

Parameters
ebufp
A pointer to an error buffer. Used to pass status information back to the caller.

Return Values

Returns a pointer to the flist in the form of pin_flist_t*.

In the case of an error, NULL is returned.

Error handling

This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Examples
The Sample Account Setup file is a C program that illustrates how to use this macro in the process of setting up a generic Portal account and service. The accompanying Makefile is also useful.

Related Information
Destroy an flist - PIN_FLIST_DESTROY() - Macro
Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro
Count fields on an flist - PIN_FLIST_COUNT() - Macro
Copy an flist - PIN_FLIST_COPY() - Macro
Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro
Sort flists - PIN_FLIST_SORT() - Macro
Print an flist - PIN_FLIST_PRINT() - Macro
Print an flist to a string - PIN_FLIST_TO_STR() - Macro
Convert an flist to XML - PIN_FLIST_TO_XML() - Macro

PIN_FLIST_DESTROY()

Description
This macro destroys an flist. Flists use dynamically allocated memory, and they must be destroyed to free that memory. This routine destroys the entire contents of an flist, including all fields on the flist.

Note PIN_FLIST_DESTROY can destroy an flist, even if the ebufp is NULL.


Synopsis
#include "pcm.h"
void PIN_FLIST_DESTROY( pin_flist_t *flistp; pin_errbuf_t *ebufp);

Parameters
*flistp
Pointer to the flist to destroy.

*ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
Nothing is returned by this routine.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Examples
The Sample Account Setup file is a C program that illustrates how to use this macro in the process of setting up a generic Portal account and service. The accompanying Makefile is also useful.

Related Information
Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro
Create an flist - PIN_FLIST_CREATE() - Macro
Count fields on an flist - PIN_FLIST_COUNT() - Macro
Copy an flist - PIN_FLIST_COPY() - Macro
Concatenate one flist onto another - PIN_FLIST_CONCAT()- Macro
Sort flists - PIN_FLIST_SORT() - Macro
Print an flist - PIN_FLIST_PRINT() - Macro
Print an flist to a string - PIN_FLIST_TO_STR() - Macro
Convert an flist to XML - PIN_FLIST_TO_XML() - Macro


PIN_FLIST_DESTROY_EX()
Description
This macro destroys an flist. Flists use dynamically allocated memory, and they must be destroyed to free that memory. This routine first checks whether the pointer passed in is NULL. If the pointer is NULL, it returns. If not NULL, then it destroys the entire contents of the flist, including all fields on the flist, and sets the flist pointer to NULL.

Note PIN_FLIST_DESTROY_EX can destroy an flist, even if the ebufp is NULL.


Synopsis
#include "pcm.h" void PIN_FLIST_DESTROY( pin_flist_t **flistpp; pin_errbuf_t *ebufp);

Parameters
**flistpp
Pointer to the flist to destroy.

*ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
Nothing is returned by this routine.

Error Handling
This routine uses the series ebuf style of error-handling. Applications can call any number of series ebuf-style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, because the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error-handling algorithms.

Examples
The Sample Account Setup file is a C program that illustrates how to use this macro in the process of setting up a generic Portal account and service. The accompanying Makefile is also useful.

Related Information

Destroy an flist - PIN_FLIST_DESTROY() - Macro
Create an flist - PIN_FLIST_CREATE() - Macro
Count fields on an flist - PIN_FLIST_COUNT() - Macro
Copy an flist - PIN_FLIST_COPY() - Macro
Concatenate one flist onto another - PIN_FLIST_CONCAT()- Macro
Sort flists - PIN_FLIST_SORT() - Macro
Print an flist - PIN_FLIST_PRINT() - Macro
Print an flist to a string - PIN_FLIST_TO_STR() - Macro
Convert an flist to XML - PIN_FLIST_TO_XML() - Macro

PIN_FLIST_COUNT()

Description
This macro counts the number of fields on the flist. Only fields on the main flist are included. Each array element and substruct are counted as a single element.

If PIN_FLIST_COUNT() is called with the pointer to an array element or substruct, the number of fields at that level of the flist is counted.

Synopsis
#include "pcm.h" int32 PIN_FLIST_COUNT( pin_flist_t *flistp; pin_errbuf_t *ebufp);

Parameters

flistp
Pointer to an flist to count the fields of.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
Returns the number of fields as an unsigned integer. Returns zero in the case of an error.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro
Destroy an flist -PIN_FLIST_DESTROY() - Macro
Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro
Copy an flist - PIN_FLIST_COPY() - Macro
Concatenate one flist on another -PIN_FLIST_CONCAT()- Macro
Sort flists - PIN_FLIST_SORT() - Macro
Print an flist - PIN_FLIST_PRINT() - Macro
Print an flist to a string -PIN_FLIST_TO_STR()- Macro
Convert an flist to XML - PIN_FLIST_TO_XML() - Macro


PIN_FLIST_COPY()
Description
Copy an existing flist. The macro copies all levels of an flist, including its array elements and substructures. The copied fields and their values are duplicated so no memory is shared between the two flists.

Synopsis
#include "pcm.h"pin_flist_t *PIN_FLIST_COPY( pin_flist_t *flistp; pin_errbuf_t *ebufp);

Parameters
flistp
Pointer to the flist to be copied.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
Returns a pointer to the new flist on completion.

Returns NULL in the case of an error.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Sort flists - PIN_FLIST_SORT() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro

Print an flist to a string - PIN_FLIST_TO_STR() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro


PIN_FLIST_CONCAT()
Description
Concatenate one flist onto another. This macro appends a (source) flist to the end of another (destination) flist. No comparisons between the flists are performed, and the source flist remains unchanged.

Synopsis
#include "pcm.h" void PIN_FLIST_CONCAT( pin_flist_t *dest_flistp; pin_flist_t *src_flistp; pin_errbuf_t *ebufp);

Parameters
dest_flistp
Pointer to the destination flist.

src_flistp
Pointer to the source flist.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
The function does not return a value; instead, the concatenated flist is returned in dest_flistp. If src_flistp is NULL, dest_flistp is returned unchanged. If dest_flistp is NULL, an error is returned in ebufp.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Sort flists - PIN_FLIST_SORT() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro

Print an flist to a string - PIN_FLIST_TO_STR() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro


PIN_FLIST_SORT()
Description
This macro sorts flists, and is normally used to sort array elements. Arrays sorted may also be the result of a search.

The flist to be sorted usually represents an array of search results returned from PCM_OP_SEARCH. The sort_flistp parameter is an flist that you construct with the sort_parameter, called PIN_FLD_RESULTS. It would look like:

PIN_FLD_RESULTS field 1 field 2 . . .

Then use the sort_default parameter to compare non-existent fields to existing fields. If all of the result elements have field value(s), 0 can be passed as the value of sort_default.

In cases where a result element has a field value, and it is being compared to another result element with the same field, but no value:


A negative sort_default means that the result element with the missing field value is sorted before the other in the sorted list.

A positive sort_default means the missing field occurs after the other.

A sort_default of 0 means that they are considered equal and order is arbitrary on the sorted list.
Synopsis
#include "pcm.h" void PIN_FLIST_SORT( pin_flist_t *flistp; pin_flist_t *sort_listp; int32 sort_default; pin_errbuf_t *ebufp);

Parameters
flistp
Pointer to the flist being sorted. The flist should normally consist of an array so that the sort is performed on elements of the array. Each element of the array may be a list of fields; it is those fields that get sorted. When you call this function, pass the exact array (flist) you want sorted, not the entire array.

sort_listp
List of fields in each element in flistp to use as sort fields. Elements in flistp are sorted in this order. If the value of this parameter is NULL, PIN_ERR_BAD_ARG is returned.

sort_default
The comparison to be used if an element is not found:

f1 NOT found, f2 found -> return sort_default
f1 found, f2 NOT found ->return -sort_default
f1 NOT found, f2 NOT found - > return 0 (equal)
a negative value for sort_default means: f1 < f2
a positive value for sort_default means: f1 > f2
a zero value for sort_default means: f1 == f2

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro

Print an flist to a string - PIN_FLIST_TO_STR() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro
PIN_FLIST_SORT_REVERSE()
Description
Sort flists in reverse order. This opcode, along with PIN_FLIST_SORT() is normally used to sort array elements. Arrays sorted may also be the result of a search.

The flist to be sorted usually represents an array of search results returned from PCM_OP_SEARCH or PCM_OP_STEP_SEARCH. The sort_flistp parameter is an flist that you construct with the sort_parameter, called PIN_FLD_RESULTS. It would look like:

PIN_FLD_RESULTS field n . . . field 2 field 1

Then use the sort_default parameter to compare non-existent fields to existing fields. If all of the result elements have field value(s), 0 can be passed as the value of sort_default.

In cases where a result element has a field value, and it is being compared to another result element with the same field, but no value:


A negative sort_default means that the result element with the missing field value is sorted after the other in the sorted list.

A positive sort_default means the missing field occurs before the other.

A sort_default of 0 means that they are considered equal and order is arbitrary on the sorted list.
Synopsis
#include "pcm.h" void PIN_FLIST_SORT( pin_flist_t *flistp; pin_flist_t *sort_listp; int32 sort_default; pin_errbuf_t *ebufp);

Parameters
flistp
Pointer to the flist being sorted. The flist should normally consist of an array so that the sort is performed on elements of the array. Each element of the array may be a list of fields; it is those fields that get sorted.

sort_listp
List of fields in each element in flistp to use as sort fields. Elements in flistp are sorted in this order. If the value of this parameter is NULL, PIN_ERR_BAD_ARG is returned.

sort_default
The comparison to be used if an element is not found:

a zero value for sort_default means: f1 == f2
a positive value for sort_default means: f1 > f2
a negative value for sort_default means: f1 < f2
f1 NOT found, f2 NOT found - > return 0 (equal)
f1 found, f2 NOT found ->return -sort_default
f1 NOT found, f2 found -> return sort_default

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Search for objects in a POD - PCM_OP_SEARCH - Opcode

Step search for objects in a POD - PCM_OP_STEP_SEARCH - Opcode

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro

Print an flist to a string - PIN_FLIST_TO_STR() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro
PIN_FLIST_PRINT()
Description
This macro prints an flist to a file in ASCII format. All levels of the flist, including the contents of array elements and substructures, are printed. This is useful for debugging applications that build or manipulate flists.

Synopsis
#include "pcm.h" void PIN_FLIST_PRINT( pin_flist_t *flistp; FILE *fi; pin_errbuf_t *ebufp);

Parameters
flistp
Pointer to the flist to print.

fi
A pointer to a file to print a message to. If the value of this pointer is NULL, the message is printed to stdout.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Examples
The Sample Account Setup file is a C program that illustrates how to use this macro in the process of setting up a generic Portal account and service. The accompanying Makefile is also useful.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Sort flists - PIN_FLIST_SORT() - Macro

Print an flist to a string - PIN_FLIST_TO_STR() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro
PIN_FLIST_TO_STR()
Description
This macro prints the contents of an flist to a buffer in ASCII form.

Synopsis
#include "pcm.h" void PIN_FLIST_TO_STR( pin_flist_t *flistp; char **strpp; int32 *lenp; pin_errbuf_t *ebufp);

Parameters
flistp
Pointer to the flist to print to a string.

strpp
A pointer to a buffer for the return string. If the value is NULL, a buffer is allocated using malloc.

lenp
The length of the buffer that strpp points to. The buffer must be large enough to include a \0. If the value of strpp is NULL, len is passed back as the size of the allocated buffer, excluding the \0.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
The string is returned in strpp. If a buffer was allocated, len is the size of the string, excluding the NULL terminator. If a buffer is allocated, the application owns the memory and must free it eventually.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Sort flists - PIN_FLIST_SORT() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro
PIN_STR_TO_FLIST()
Description
This macro take a string representation of an flist (for example, the output of PIN_FLIST_TO_STR()) and creates an flist run-time data structure.

Synopsis
#include "pcm.h" void PIN_STR_TO_FLIST( char *str; int64 default_db; pin_flist_t **flistp; pin_errbuf_t *ebufp);

Parameters
str
Pointer to a string containing an flist in ASCII form.

default_db
A specified database number. If the ASCII string contains the sub string "$DB", then the database number in this parameter will replace it.

flistp
Pointer to a buffer for the return flist.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
The string is returned in flistp.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Sort flists - PIN_FLIST_SORT() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro

Convert an flist to XML - PIN_FLIST_TO_XML() - Macro
PIN_FLIST_TO_XML()
Description
This macro converts an flist to XML format. It is designed for converting an invoice to an XML format. The formatted XML invoice is generated directly from the flist. It ignores and doesn't convert data in buffer fields or fields of type PIN_FLDT_BINSTR.

Note This macro does not generate a .DTD file.


Synopsis
#include "pcm.h" void PIN_FLIST_TO_XML( pin_flist_t *flistp; int32 flags; int32 encoding; char **bufpp; int *lenp; char *root_elemname; pin_errbuf_t *ebufp);

Parameters
flistp
Pointer to the flist to convert.

flags
Specifies the name/attribute pairs to use for the XML element tag.

PIN_XML_BY_TYPE
Uses the TYPE field for the name of the XML element tag. This is the default.

PIN_XML_BY_NAME
Uses the field name for the name of the XML element tag.

PIN_XML_BY_SHORT_NAME
Uses the field name for the name of the XML element tag and drops the common prefix to include only the unique portion. For example, "PIN_FLD_NAME" becomes "NAME".

PIN_XML_FLDNO
Uses the field number for the attribute of the XML element tag.

PIN_XML_TYPE
Uses the TYPE field for the attribute of the XML element tag.

encoding
Specify UTF8.

bufpp
A pointer to the buffer that will contain the XML converted data.

lenp
The size of the buffer that bufpp points to.

root_elemname
The root element name. If you don't specify this field, the default root element name, "document", is used.

ebufp
Pointer to an error buffer. Used to pass status information back to the caller.

Return Values
Nothing is returned by this routine.

Error Handling
This routine utilizes the series ebuf style of error handling. Applications can call any number of series ebuf style API routines using the same ebuf, and only check for errors once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient, since the entire logical operation can be completed, then tested once for any errors. See Understanding API Error Handling and Logging for details on error handling algorithms.

Related Information

Create an flist - PIN_FLIST_CREATE() - Macro

Destroy an flist - PIN_FLIST_DESTROY() - Macro

Destroy an flist - PIN_FLIST_DESTROY_EX() - Macro

Count fields on an flist - PIN_FLIST_COUNT() - Macro

Copy an flist - PIN_FLIST_COPY() - Macro

Concatenate one flist on another - PIN_FLIST_CONCAT() - Macro

Sort flists - PIN_FLIST_SORT() - Macro

Print an flist to a string - PIN_FLIST_TO_STR() - Macro

Print an flist - PIN_FLIST_PRINT() - Macro


--------------------------------------------------------------------------------