Skip Headers
Oracle® Communications Billing and Revenue Management Developer's Reference
Release 7.5

E16714-11
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 PIN Libraries Reference

This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) Portal Information Network (PIN) libraries.

Configuration File-Reading Functions

Use these functions to read configuration files, such as pin.conf files.

pin_conf

This BRM library routine reads a single configuration value from a configuration file.

The Connection Manager (CM), Data Manager (DM), and Portal Communications Module (PCM) libraries all use this routine to read the configuration information.

When first called, this routine looks for the configuration file specific to the application. See "Locations of Configuration and Properties Files" in BRM System Administrator's Guide. The library returns an error if it cannot locate the configuration file.

This routine uses regular malloc. If you are using this routine in a Storage Manager to get data to put on an flist, use SET (not PUT), and then free the storable object by using the regular free routine when you are finished.

Important:

Do not use this routine if performance is a consideration and you use the routine often.

For more information on configuration files, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

For information on reading multiple configuration values from a file, see "pin_conf_multi".

Syntax

#include "pcm.h" 
void 
pin_conf(
               char          *prog_name,
               char          *token,
               int32          valtype,
               caddr_t*     **valpp,
               int32         *errp);

Parameters

prog_name

The program name this routine looks for in the configuration file. If prog_name is NULL, the routine looks only for entries marked with a program of "-". If prog_name is any other value, the routine looks for either a specific match or "-" in the program parameter. For a description of configuration file syntax, see "Configuration Entry Syntax" in BRM System Administrator's Guide.

token

The name of the configuration entry keyword this routine looks for in the configuration file.

valtype

The type of the value the routine reads in the configuration entry. This parameter tells the routine how to interpret the entry value. The supported types are:

  • PIN_FLDT_INT

  • PIN_FLDT_DECIMAL

  • PIN_FLDT_STR

  • PIN_FLDT_POID

valpp

The ptr-ptr used to pass back the location of the value for the entry. The memory for the value is dynamically allocated, and the filled-in pointer type matches the value type.

errp

A pointer to the error buffer, which passes error information back to the caller.

Return Values

This routine returns nothing.

This routine passes error status back to the caller. If it finds a matching entry in the configuration file, it passes back PIN_ERR_NONE. If it does not find a matching entry, it passes back PIN_ERR_NOT_FOUND. The routine might also pass back other error values.

pin_conf_beid

This library routine reads values for BRM resources from the /config/beid storable object.

Syntax

#include "pin_errs.h" 
#include "pcm.h"
pin_flist_t*
pin_conf_beid(
               pcm_context_t     *ctxp,
               pin_errbuf_t      *ebufp);

Parameters

ctxp

A pointer to an open context. This routine gets the database number from the configuration file of the current application and queries that database for the /config/beid object.

ebufp

A pointer to the error buffer, which passes error information back to the caller.

Return Values

Returns values for the /config/beid storable object data as an flist.

Error Handling

This routine sets the return flist to NULL and provides more information about the error in the error buffer if there is an error.

pin_conf_multi

This library routine reads multiple configuration values of the same type from a configuration file. To do this, you reuse this routine until it returns PIN_ERR_NOT_FOUND. This routine uses the time_t value to monitor the configuration file for changes throughout this operation and returns an error if the state of the file changes.

The Connection Manager (CM), Data Manager (DM), and PCM libraries all use this routine to read the configuration information.

When first called, this routine looks for the configuration file specific to the application. See "Locations of Configuration and Properties Files" in BRM System Administrator's Guide. The library returns an error if it cannot locate the configuration file.

This routine uses regular malloc. If you are using this routine in a Storage Manager to get data to put on an flist, use SET (not PUT), and then free the storable object by using the regular free routine when you are finished.

Important:

Do not use this routine if performance is a consideration and you use the routine often.

For more information on configuration files, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

For information on reading a single configuration value from a file, see "pin_conf".

Syntax

#include "pcm.h" 
void 
pin_conf(
               char          *prog_name,
               char          *token,
               int32          valtype,
               caddr_t*     **valpp,
               int32         *linep,
               time_t        *modtp,
               int32         *errp);

Parameters

prog_name

The program name this routine looks for in the configuration file. If prog_name is NULL, the routine looks only for entries marked with a program of "-". If prog_name is any other value, the routine looks for either a specific match or "-" in the program parameter. For a description of configuration file syntax, see "Configuration Entry Syntax" in BRM System Administrator's Guide.

token

The name of the configuration entry keyword this routine looks for in the configuration file.

valtype

The type of the value the routine reads in the configuration entry. This parameter tells the routine how to interpret the entry value. The supported types are:

  • PIN_FLDT_INT

  • PIN_FLDT_DECIMAL

  • PIN_FLDT_STR

  • PIN_FLDT_POID

valpp

The ptr-ptr used to pass back the location of the value for the entry. The memory for the value is dynamically allocated, and the filled-in pointer type matches the value type.

linep

A pointer to a line number. Passes an integer back to the caller to identify the line where the last value was found. Initialize to zero on the first call.

modtp

A pointer to a time variable. Passes a timestamp back to the caller to compare to the last timestamp. Initialize to zero on the first call.

errp

A pointer to the error status, which passes error information back to the caller.

Return Values

This routine returns nothing.

This routine passes error status back to the caller.

  • If it finds a matching entry in the configuration file, it passes back PIN_ERR_NONE. This indicates that the routine then reuses the key to look for another matching entry (as long as it has not generated a PIN_ERR_STALE_CONF error).

  • If it does not find a matching entry, it passes back PIN_ERR_NOT_FOUND. This signals the end of the routine.

  • If it detects, based on a change in the time_t value, that the configuration file has been opened, modified, or has otherwise changed since it first accessed the file (jeopardizing the ability of the routine to maintain correct reference to the last value read), it passes back PIN_ERR_STALE_CONF.

    Important:

    In this case, you must restart the entire process.

The routine may also pass back other error values.

Decimal Data Type Manipulation Functions

This section describes decimal data type manipulation functions.

About Using the API

The decimal data type application programming interface (API) consists of a minimal set of methods that provides all the functionality you need to perform basic mathematical functions, comparison, and format conversion with the decimal data type. Input and output to the functions are provided using number strings or floating point doubles.

Tip:

Use strings to avoid small quantity errors; for example, 31.299999999 vs. 31.3.

If there are errors, functions that return a pin_decimal_t return NULL. pbo_decimal_destroy allows NULL.

International Platform Issues

The pin_decimal function expects the decimal point character to be that of the locale. For US systems, this is a period; for most international platforms, it is a comma.

Caution:

Do not pass a string with a hard-coded decimal point to ::pin_decimal because pin_decimal will return a NULL pointer in platforms that do not use a period for the decimal point character.

About Rounding Modes

This section defines the rounding modes that you pass as input parameters in the following functions:

The rounding modes in Table 2-1 are defined in pcm.h. They have the same names and functionality as the Java BigDecimal Datatype.

Table 2-1 Rounding Modes

Rounding Mode Description

ROUND_UP

Rounds up to the nearest number of the appropriate scale.

Examples: 21.11 rounds to 21.2 when the scale is one decimal place.

ROUND_DOWN

Rounds down to the nearest number of the appropriate scale.

Examples: 21.19 rounds to 21.1 when the scale is one decimal place.

ROUND_DOWN_ALT

Rounds down after first rounding to the nearest using a scale of two more than the one configured. This method compensates for possible loss of precision when numbers are rounded down during certain computations, such as when prorating cycle fees.

For more information, see "About Rounding Modes That Correct for Loss of Precision" in BRM Setting Up Pricing and Rating.

ROUND_CEILING

If the number is positive, rounding is the same as for ROUND_UP; if negative, the same as for ROUND_DOWN.

ROUND_FLOOR

If the number is positive, rounding is the same as for ROUND_DOWN; if negative the same as for ROUND_UP. This method allows you to round to benefit customers. For example, if rounding is set to two significant digits, a credit to a customer of -7.999 is rounded to -8.00, and a debit of 7.999 is rounded to 7.99.

ROUND_FLOOR_ALT

Rounds using ROUND_FLOOR after first rounding to the nearest using a scale of two more than the one configured. This method compensates for possible loss of precision when numbers are rounded down during certain computations, such as when prorating cycle fees.

For more information, see "About Rounding Modes That Correct for Loss of Precision" in BRM Setting Up Pricing and Rating.

ROUND_HALF_UP

If the discard part is .5 or higher round up; otherwise, round down.

Examples: 21.15 rounds to 21.2, 21.14 rounds to 21.1, etc.

This is the most common rounding method.

ROUND_HALF_DOWN

If the discard part is more than .5, round up; if it is .5 or less, round down.

Examples: 21.16 rounds to 21.2, 21.15 rounds to 21.1.

ROUND_HALF_EVEN

If the digit to the left of the discard is odd, rounding is the same as for ROUND_HALF_UP. If the digit to the left is even, rounding is the same as for ROUND_HALF_DOWN.

Examples:

1.049 rounds to 1.0

1.050 rounds to 1.0

1.051 rounds to 1.1

1.149 rounds to 1.1

1.150 rounds to 1.2

1.151 rounds to 1.2

ROUND_UNNECESSARY

Rounding not allowed. If rounding is attempted with this rounding mode, an error is returned.


About Scaling

A decimal data type is based on the Java BigDecimal data type. It is an immutable, arbitrary-precision signed decimal number, which consists of an arbitrary precision integer value and a non-negative integer scale, which represents the number of decimal digits to the right of the decimal point.

For this implementation, the scale is set at 15, meaning numbers carry up to 15 decimal places. For operations that would normally result in a value with a larger scale, the value is rounded to 15 decimal places. For example, when multiplying the two decimal data types 12.528694120521357 and 4.126943650923412, the mathematical result would normally be 51.705214655047095455751917310084, which has a scale of 30. However, because the scale is set at 15, the product is rounded to 51.705214655047095 and a consistent scale of 15 is maintained.

About Memory Management

For functions that allocate memory for the pin_decimal_t structure, make sure that the memory is reclaimed after the pin_decimal_t is no longer needed. If pin_decimal_t has been passed to an flist with PIN_FLIST_PUT, use pin_flist_destroy to reclaim memory. Otherwise, use pbo_decimal_destroy.

assign functions do not allocate new memory; instead, they replace the first parameter with the new value. Therefore, there is no need to reclaim memory.

pbo_decimal_abs

This function returns a pointer to a newly allocated pin_decimal_t, which is the absolute value of the input pin_decimal_t.

Syntax

pin_decimal_t*
pbo_decimal_abs(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_abs_assign

This function replaces the input pin_decimal_t with its absolute value.

Syntax

pin_decimal_t*
pbo_decimal_abs_assign(
               pin_decimal_t     *pdp, 
               pin_errbuf_t      *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_add

This function adds the two decimals passed in and returns a pointer to a newly allocated pin_decimal_t. The scale of the output is the larger of the scales of the two inputs.

Syntax

pin_decimal_t*
pbo_decimal_add(
               const pin_decimal_t     *pdp1, 
               const pin_decimal_t     *pdp2, 
               pin_errbuf_t            *ebufp);

Parameters

pdp1

A pointer to the input pin_decimal_t.

pdp2

A pointer to another input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_add_assign

This function replaces the value of the first pin_decimal_t with the sum of itself and another pin_decimal_t.

Syntax

void 
pbo_decimal_add_assign( 
               pin_decimal_t           *pdp1, 
               const pin_decimal_t     *pdp2, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_compare

This function compares the first input decimal with the second input decimal and returns one of the following values to indicate the difference between the input decimals:

  • -1 if pdp1 < pdp2

  • 0 if pdp1 = pdp2

    Note:

    pdp1 is considered equal to pdp2 if the difference between them is less than 10-12.
  • 1 if pdp1 > pdp2

  • 0 in the event of an error.

Syntax

int 
pbo_decimal_compare(
               const pin_decimal_t     *pdp1, 
               const pin_decimal_t     *pdp2, 
               pin_errbuf_t            *ebufp);

Parameters

pdp1

A pointer to the first pin_decimal_t.

pdp2

A pointer to the second pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_copy

This function makes a copy of the input pin_decimal_t and returns a pointer to the newly allocated pin_decimal_t.

Syntax

pin_decimal_t*
pbo_decimal_copy(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_destroy

This function frees all the memory associated with the specified pin_decimal_t and sets *decpp to NULL.

Syntax

void 
pbo_decimal_destroy(
               pin_decimal_t     **decpp);

Parameter

decpp

A pointer to a pointer to the pin_decimal_t to be deleted. Can be set to NULL (the function does nothing).

pbo_decimal_divide

This function divides the first input parameter by the second input parameter and returns a pointer to a newly allocated pin_decimal_t.

Note:

Rounding is performed according to preset rounding and scaling. The default rounding mode is ROUND_DOWN and the scaling is set at 15 decimal places.

Syntax

pin_decimal_t*
pbo_decimal_divide(
               const pin_decimal_t     *nump, 
               const pin_decimal_t     *byp, 
               pin_errbuf_t            *ebufp);

Parameters

nump

A pointer to the dividend.

byp

A pointer to the divisor.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_BAD_ARG if one of the following is true:

    • The scale is less than 0.

    • The rounding mode is unknown.

    • Either the dividend or the divisor is not a valid pin_decimal_t.

    • An attempt was made to divide by 0.

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_divide_assign

This function divides the dividend by the divisor and stores the result in the dividend.

Syntax

void 
pbo_decimal_divide_assign(
               pin_decimal_t           *nump, 
               const pin_decimal_t     *byp, 
               pin_errbuf_t            *ebufp);

Parameters

nump

A pointer to the dividend.

byp

A pointer to the divisor.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_BAD_ARG if one of the following is true:

    • The scale is less than 0.

    • The rounding mode is unknown.

    • Either the dividend or the divisor is not a valid pin_decimal_t.

    • An attempt was made to divide by 0.

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_from_double

This function constructs a pin_decimal_t data type from the double-precision floating point number (allocates memory) and returns a pointer to the newly created pin_decimal_t data type.

Note:

Because of the inherent rounding errors associated with converting a double to a decimal data type, you should avoid using this function whenever possible. Use pbo_decimal_from_str instead. If you must use doubles, use the pbo_decimal_from_double_round function.

Syntax

pin_decimal_t 
*pbo_decimal_from_double(
               double            d, 
               pin_errbuf_t     *ebufp);

Parameters

d

The input of type double float (a double-precision floating point number).

ebufp

A pointer to the error buffer.

See also "pbo_decimal_from_str".

pbo_decimal_from_double_round

This function provides an option for choosing the rounding mode. (See "About Rounding Modes".)

Constructs a pin_decimal_t data type from the double-precision floating point number (allocates memory) and returns a pointer to the newly created pin_decimal_t data type.

Note:

Because of the inherent rounding errors associated with converting a double to a decimal data type, you should avoid using this function whenever possible. Use pbo_decimal_from_str instead.

Syntax

pin_decimal_t*
pbo_decimal_from_double_round(
               double            value, 
               int               rounding_mode, 
               pin_errbuf_t     *ebufp)

Parameters

value

The value to convert.

rounding_mode

See "About Rounding Modes".

ebufp

A pointer to the error buffer.

pbo_decimal_from_str

This function constructs a pin_decimal_t data type from an input string and returns a pointer to the newly created pin_decimal_t data type.

This function understands NULL to create a NULL-valued pin_decimal_t. The string does not need to end with a null character, but parsing will end at either a null character or any white space character.

This function ignores leading spaces, tabs, and leading 0's and checks on non-numeric types.

This function detects the sign (+ or -) and stores it. This function accepts the same input at strtod except that an exponent is not allowed, and only base 10 is supported.

Syntax

pin_decimal_t*
pbo_decimal_from_str(
               const            *str, 
               pin_errbuf_t     *ebufp);

Parameters

str

The input number string.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the string pointer is NULL

  • PIN_ERR_BAD_ARG if there were multiple decimal points before null or space or if it cannot derive a valid number from the string

  • PIN_ERR_NO_MEM if the function cannot allocate memory for pbo_decimal

pbo_decimal_is_null

This function verifies if the input pin_decimal_t is NULL.

Syntax

int 
pbo_decimal_is_null(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

The pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns PIN_ERR_BAD_ARG indicating that a non-NULL pointer points to a data area not marked as a valid pin_decimal_t.

pbo_decimal_is_zero

This function checks if the input value is a valid pin_decimal_t and has a zero value. Returns 1 if the conditions are met; otherwise, it returns 0.

Syntax

int 
pbo_decimal_is_zero(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns PIN_ERR_BAD_ARG indicating that a non-NULL pointer points to a data area that is not marked as a valid pin_decimal_t.

pbo_decimal_multiply

This function multiplies the two input pin_decimal_t values and returns a pointer to a new pin_decimal_t that is the product.

Syntax

pin_decimal_t*
pbo_decimal_multiply(
               const pin_decimal_t     *pdp1, 
               const pin_decimal_t     *pdp2, 
               pin_errbuf_t            *ebufp);

Parameters

pdp1

The pointer to an input pin_decimal_t.

pdp2

The pointer to another input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_multiply_assign

This function multiplies two pin_decimal_t data types and stores the product in the first pin_decimal_t.

For example, if a=10 and b=2, after calling pbo_decimal_multiply_assign(a, b, *ebufp), a is equal to 20.

Syntax

void 
pbo_decimal_multiply_assign(
               pin_decimal_t           *pdp1, 
               const pin_decimal_t     *pdp2, 
               pin_errbuf_t            *ebufp);

Parameters

pdp1

The pointer to an input pin_decimal_t.

pdp2

The pointer to another input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

pbo_decimal_negate

This function returns a pointer to a new pin_decimal_t that has the reverse sign of the input decimal. If the input decimal has a value of 0, it returns a pointer to another pin_decimal_t with the value of 0.

Table 2-2 contains examples, where x is a pointer pin_decimal_t:

Table 2-2 pbo_decimal_negate Examples

Value to Which x Points pbo_decimal_negate(x, ebuf) Returns a New Pointer to This Value:

5

-5

0

0

-3

3

Value to which x points

pbo_decimal_negate(x, ebuf) returns a new pointer to a value of:


Syntax

pin_decimal_t*
pbo_decimal_negate(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

The pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_negate_assign

This function reverses the sign of the input pin_decimal_t.

Syntax

pin_decimal_t*
pbo_decimal_negate_assign(
               pin_decimal_t     *pdp, 
               pin_errbuf_t      *ebufp);

Parameters

pdp

The pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

pbo_decimal_round

This function returns a pointer to a new pin_decimal_t that contains the value of the first argument rounded according to the specified scale and rounding mode.

Syntax

pin_decimal_t*
pbo_decimal_round(
               const pin_decimal_t     *decp, 
               int32                    scale, 
               int32                    rounding_mode, 
               pin_errbuf_t            *ebufp);

Parameters

decp

A pointer to the input pin_decimal_t.

scale

See "About Scaling".

rounding_mode

See "About Rounding Modes".

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_round_assign

This function replaces the value of the first argument with the value of the argument rounded according to the specified scale and rounding mode.

Syntax

void 
pbo_decimal_round_assign( 
               pin_decimal_t     *decp, 
               int32              scale, 
               int32              rounding_mode, 
               pin_errbuf_t      *ebufp);

Parameters

decp

A pointer to the input pin_decimal_t.

scale

See "About Scaling".

rounding_mode

See "About Rounding Modes".

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_BAD_ARG if decp is an invalid value

pbo_decimal_sign

This function returns the sign of the pin_decimal_t argument: -1 if the argument is negative, 0 if the argument is zero or if there is an error, or 1 if the argument is positive.

Syntax

int 
pbo_decimal_sign(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

The pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

pbo_decimal_subtract

This function subtracts two pin_decimal_t parameters and returns a pointer to a new pin_decimal_t containing the difference.

Syntax

pin_decimal_t*
pbo_decimal_subtract(
               const pin_decimal_t     *nump,
               const pin_decimal_t     *byp, 
               pin_errbuf_t            *ebufp);

Parameters

nump

The pointer to the pin_decimal_t from which to subtract.

byp

The pointer to the pin_decimal_t to subtract.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

pbo_decimal_subtract_assign

This function subtracts a decimal from another decimal and replaces the value of the first decimal with the difference.

For example, if a=8 and b=3, after calling pbo_decimal_subtract_assign (a, b, ebuf), a is equal to 5.

Syntax

void 
pbo_decimal_subtract_assign(
               pin_decimal_t           *pdp1, 
               const pin_decimal_t     *pdp2, 
               pin_errbuf_t            *ebufp);

Parameters

pdp1

The pointer to an input pin_decimal_t.

pdp2

The pointer to another input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

pbo_decimal_to_double

This function converts the input pin_decimal_t into a double-precision floating point number.

If pin_decimal_t is not NULL, this function converts pin_decimal_t to a string using pin_decimal_to_str(NULL format,...) and then strtod.

Syntax

double 
pbo_decimal_to_double(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

  • PIN_ERR_BAD_ARG if strtod returns an error

See also pin_decimal_to_str().

pbo_decimal_to_str

This function creates an ASCII string representation of the input decimal value.

If successful, the function returns a pointer to the allocated null-terminated string. If there are errors, it returns NULL.

Syntax

char*
pbo_decimal_to_str(
               const pin_decimal_t     *pdp, 
               pin_errbuf_t            *ebufp);

Parameters

pdp

A pointer to the input pin_decimal_t.

ebufp

A pointer to the error buffer.

Error Handling

If there are errors, this function returns the following error status:

  • PIN_ERR_NULL_PTR if the input pin_decimal_t pointer is NULL

  • PIN_ERR_IS_NULL if the input pin_decimal_t is NULL-valued

  • PIN_ERR_NO_MEM if the function cannot allocate memory for the output pin_decimal_t

Error-Handling Macros

This section describes error-handling macros.

PIN_ERR_LOG_EBUF

This BRM macro logs a standardized message that includes details of the error condition recorded in an error buffer. It provides a convenient method for logging errors returned by API calls that use the error buffer to pass back status. The caller can specify an additional message that is appended to the standard format.

Syntax

#include "pcm.h" 
void 
PIN_ERR_LOG_EBUF(
                 int32          level,
                 char          *msg,
                 pin_errbuf_t  *ebufp);

Parameters

level

The level of this log message. Based on the level specified and the logging level set in the log system, the message is either printed or discarded. See "PIN_ERR_SET_LEVEL" for the error level descriptions.

msg

A string to be printed in addition to the standard logging message. Allows additional detailed information to be added to the log message by the caller.

ebufp

A pointer to the error buffer containing the error condition. The values in the error buffer are printed in human-readable form as part of the log message.

Return Values

This macro returns nothing.

Error Handling

There are no error conditions for this macro. If the message cannot be logged for any reason, that information is not passed back to the caller.

PIN_ERR_LOG_FLIST

This macro prints the contents of an flist to the error log file. It allows an application to log an arbitrary message and the corresponding flist for recording errors, accounting, or debugging. The specified message and flist are logged in the standard log entry format, so complete information about where they came from is available in the log file.

Syntax

#include "pcm.h" 
void 
PIN_ERR_LOG_FLIST(
                 int32         level,
                 char         *msg,
                 pin_flist_t  *flistp);

Parameters

level

The level of this log message. Based on the level specified and the logging level set in the log system, the message is either printed or discarded. See "PIN_ERR_SET_LEVEL" for the error-level descriptions.

msg

A string to be printed in addition to the standard logging message. Allows additional detailed information to be added to the log message by the caller.

flistp

A pointer to the flist to be printed in addition to the log message.

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_ERR_LOG_MSG

This macro logs the specified message to the log file. It allows an application to log arbitrary messages for recording errors or debug information. The specified message is logged in the standard log entry format, so complete information about where the message came from is available in the log file.

Syntax

#include "pcm.h" 
void 
PIN_ERR_LOG_MSG(
                 int32     level,
                 char     *msg);

Parameters

level

The level of this log message. Based on the level specified and the logging level set in the log system, the message is either printed or discarded. See "PIN_ERR_SET_LEVEL" for the error-level descriptions.

msg

A string to be printed in addition to the standard logging message. Allows additional detailed information to be added to the log message by the caller. Special characters should be escaped if you want them to be printed without modification.

Return Values

This macro returns nothing.

Error Handling

There are no error conditions for this macro. If the message cannot be logged for any reason, that information is not passed back to the caller.

PIN_ERR_LOG_POID

This macro prints the contents of a POID to the error log file. This operation allows an application to log an arbitrary message and the corresponding POID for recording errors, accounting, or debugging. The specified message and POID are logged in the standard log entry format, so complete information about where they came from is available in the log file.

Syntax

#include "pcm.h" 
void 
PIN_ERR_LOG_POID(
                 int32     level,
                 char     *msg,
                 poid_t   *pdp);

Parameters

level

The level of this log message. Based on the level specified and the logging level set in the log system, the message is either printed or discarded. See "PIN_ERR_SET_LEVEL" for the error-level descriptions.

msg

A string to be printed in addition to the standard logging message. Allows additional detailed information to be added to the log message by the caller.

pdp

A pointer to the POID to be printed in addition to the standard log entry information.

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_ERR_SET_LEVEL

This macro sets the desired level of logging. Messages sent to the logging system have a severity code that describes the category of the message. Users can chose to have messages of different categories either logged or suppressed, depending on how much logging output they would like to see. Messages that are suppressed are discarded.

In general, BRM recommends that only debug messages be suppressed on a production system. All other types of messages convey possible system problems that should be investigated. Debug messages can be enabled when they might help diagnose an application error and then suppressed when the system is running in a steady state.

If PIN_ERR_SET_LEVEL is not called, the logging system defaults to a level of 2.

Syntax

#include "pcm.h" 
int32 
PIN_ERR_SET_LEVEL(
                 int32     level);

Parameter

level

Sets the mask for which level of errors should be logged and which ones suppressed. All messages with a level of level or less are printed. All messages with a level greater than level are suppressed. Errors come in the levels listed in Table 2-3:

Table 2-3 PIN_ERR_SET_LEVEL Values

Allowed Level Values System Category Type of Message Messages Returned

0

N/A

N/A

Nothing at this level

1

E

Error

Serious system integrity problems

2

W

Warning

Possible data corruption problems

3

D

Debug

Details of application errors


  • Setting level to 0 means no messages will be produced, no matter what the error.

  • Setting level to 1 will log only errors, which indicate some portion of the BRM system is not operating correctly.

  • Setting level to 2 will print errors and warnings. Warnings indicate that data was found in the database that is suspect, and some data corruption may have occurred. The system can still operate properly, but specific operations related to the corrupt data may have to be bypassed.

  • Setting level to 3 prints debug messages. The debug messages log detailed information about operations that applications attempt that generate errors in the system due to incorrect parameters or other application level errors. The system is not adversely affected by this type of event, but the application developer can use the debug messages to more easily pinpoint where the application error is located.

Return Values

Returns 0 if the macro is successful. Returns a non-zero value if an error occurred. The only possible failure is the specification of an unreasonable value for level.

Error Handling

Returns a non-zero value if an error occurred. In this case, the internal state of the logging system is unchanged.

PIN_ERR_SET_LOGFILE

This macro specifies the file to use for logging. The log file can be changed at any time by calling PIN_ERR_SET_LOGFILE. All messages logged after the change are logged to the new file.

If this macro is not called, the logging system uses the default ./default.pinlog log file, where ./ is relative to the directory in which the application was started.

Syntax

#include "pcm.h" 
int32 
PIN_ERR_SET_LOGFILE(
                 char     *path);

Parameter

path

The path of the file to be used as the log file. The file is opened exactly as specified, so relative paths will work, but they will be relative to the current directory of the running program.

Return Values

Returns a non-zero value if an error occurred.

Error Handling

Returns a non-zero value if an error occurred. The internal state of the logging system is unchanged. The return value should be tested after the call to ensure the desired log file will be used.

PIN_ERR_SET_PROGRAM

This macro sets the program name for log messages. The program name is printed in each log message as additional information to aid in debugging problems. The program name can be set to any string desired.

If PIN_ERR_SET_PROGRAM is not called, log messages are printed with a blank program name field.

Syntax

#include "pcm.h" 
int32 
PIN_ERR_SET_PROGRAM(
                 char     *program);

Parameter

program

The name of the running program to be printed in log messages. If the pointer is NULL, the current name is not changed.

Return Values

Returns 0 if the macro is successful. Returns a non-zero value if an error occurred. The only possible failure condition is the specification of a NULL pointer.

Error Handling

Returns a non-zero return value if an error occurred. In this case, the internal state of the logging system is unchanged.

PIN_ERRBUF_CLEAR

This macro is used for a newly allocated or defined error buffer structure to initialize the contents of the error buffer to 0.

Syntax

#include "pcm.h" 
void 
PIN_ERRBUF_CLEAR(
                 pin_errbuf_t     *ebufp);

Parameter

ebufp

A pointer to the error buffer that is initialized.

Return Values

This macro returns nothing.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_ERRBUF_IS_ERR

This macro checks the specified error buffer for an error condition. It allows an application to quickly check whether an error has occurred on a call that used the error buffer.

Macros that use individual ebuf error handling must use PIN_ERRBUF_IS_ERR after each call to test for an error.

Macros that use series-style ebuf error handling can make an entire series of calls and use this macro once at the end to test for an error.

Syntax

#include "pcm.h" 
int32 
PIN_ERRBUF_IS_ERR(
                 pin_errbuf_t     *ebufp);

Parameter

ebufp

A pointer to an error buffer. Used by the macro to determine whether an error has occurred.

Return Values

Returns 0 if the error buffer contains no error. Returns a non-zero value if the error buffer contains an error.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_ERRBUF_RESET

This macro is called to reset the error buffer either before reusing an existing error buffer structure or before calling pin_free to free a dynamically allocated error buffer structure.

For details on the structure and fields in an error buffer, see "Error Buffer" in BRM Developer's Guide.

The use of PIN_ERRBUF_RESET depends on the type of macro called with the error buffer:

  • Individual-style ebuf: Macros that use this style of error handling must examine the error buffer for an error after each call. Use PIN_ERRBUF_RESET to clear any error that was detected before using the same error buffer again.

  • Series-style ebuf: Macros that use this style of error handling can use the same error buffer for a series of calls without checking for or clearing errors between calls. After a series of calls, check the error buffer for errors. Use PIN_ERRBUF_RESET to clear any error before using the error buffer again.

Syntax

#include "pcm.h" 
void 
PIN_ERRBUF_RESET(
                 pin_errbuf_t     *ebufp);

Parameter

ebufp

A pointer to the error buffer that is reset.

Return Values

This macro returns nothing.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

pin_set_err

This function sets the error values in the pin_errbuf_t (ebuf) structure pointer.

Note:

This is the only error handling routine that is not a macro. This is a function.

Syntax

EXTERN 
void 
pin_set_err(
               pin_errbuf_t    *ebuf, 
               int32            location,
               int32            pin_errclass, 
               int32            pin_err,
               int32            field, 
               int32            rec_ID,
               int32            reserved); 

Parameters

ebuf

A pointer to the error buffer.

location

The location of an error. For a list of possible locations, see "BRM Error Locations" in BRM System Administrator's Guide.

pin_errclass

One of the four classes. See "BRM Error Classes" in BRM System Administrator's Guide.

pin_err

One of the system error codes. For a list of possible error codes, see "BRM Error Codes"in BRM System Administrator's Guide.

field

Set to 0 or to the applicable PIN_FLD_xxx.

rec_ID

Set to 0 or to the record ID of the array element the error occurred on.

reserved

Set to 0 or to a value chosen to provide further information about the specific error.

Return Values

This function returns nothing.

Error Handling

There are no error conditions for this function. If the message cannot be logged for any reason, that information is not passed back to the caller.

Flist Field-Handling Macros

This section describes flist field-handling macros.

PIN_FLIST_ANY_GET_NEXT

This BRM macro gets the value of the next simple field, substructure, or element of an array in an flist. It lets an application walk an flist retrieving each field value.

The value returned is a pointer to the actual field value, and the field remains unchanged on the original flist. The value returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the value is needed, the application must either make a copy of the returned value or take it according to its type as listed in Table 2-4:

Table 2-4 Next Field Macros

Field Type Macro to Use

Simple

PIN_FLIST_FLD_TAKE

Substructure

PIN_FLIST_SUBSTR_TAKE

Array element

PIN_FLIST_ELEM_TAKE


Syntax

#include "pcm.h" 
void 
*PIN_FLIST_ANY_GET_NEXT(
                 pin_flist_t     *flistp,
                 pin_fld_num_t   *fldp,
                 int32           *record_idp,
                 pin_cookie_t    *cookiep,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the field being obtained.

fldp

A pointer to the field.

record_idp

The element ID, in case of array field is returned if not NULL.

cookiep

The cookie for the next field.

ebufp

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

Return Values

Returns a pointer to the value on the flist. The pointer must be cast appropriately depending on the type of the field. Returns NULL if an error occurred or if the field is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_ADD

This macro adds a specified array element to the flist. The flist for the element fields is created and returned. The pointer to this element flist can then be used to set/put fields into the element.

If the specified array element already exists on the flist, the existing element flist is destroyed and replaced by the new element flist.

Syntax

#include "pcm.h" 
pin_flist_t * 
PIN_FLIST_ELEM_ADD(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 v_int32          elem_id,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist receiving the array element.

fld

The number of the field being added.

elem_id

The element ID of the element being added.

ebufp

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

Return Values

Returns a pointer to the flist for the array element. Returns NULL if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_ELEM_COPY

This macro copies an element in an array from one flist to another. You can change the element name and record ID while copying the element. The type must remain the same.

Syntax

#include "pcm.h" 
int32
PIN_FLIST_ELEM_COPY(
                 pin_flist_t    *src_flistp,
                 pin_fld_num_t   src_fld,
                 pin_rec_id_t    src_recID,
                 pin_flist_t    *dest_flistp,
                 pin_fld_num_t   dest_fld,
                 pin_rec_id_t    dest_recID,
                 pin_errbuf_t    *ebufp );

Parameters

src_flistp

A pointer to the source flist from which the element is copied.

src_fld

The element that is copied from the source flist.

src_recID

The record ID of the element that is copied.

dest_flistp

A pointer to the destination flist to which an element is copied.

dest_fld

The copied element in the destination flist.

dest_recID

The record ID of the copied element in the destination flist.

ebufp

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

Return Values

Returns 1 if the field to be copied is found. Returns 0 if the field to be copied is not found. Not finding a field does not result in an error buffer error.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_COUNT

This macro counts the number of elements of an array on an flist. It does not look at substructure flists, so the elements must be on the flist passed in at the highest level.

Syntax

#include "pcm.h" 
int32 
PIN_FLIST_ELEM_COUNT(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist being counted.

fld

The field number of the array containing the elements being counted. Each time a field with this number is found, the element count is incremented.

ebufp

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

Return Values

Returns the number of elements found as an unsigned integer. Returns 0 if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_DROP

This macro drops the specified array element from an flist. The element flist is destroyed and the memory reallocated.

Important:

This opcode causes an array to shift its indexing if an element other than the last is dropped. Do not use this PIN_FLIST_ELEM_DROP in a loop of PIN_FLIST_ELEM_GET_NEXT calls; the off-set will cause elements to be skipped.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_ELEM_DROP(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32            elem_id,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the array element being removed.

fld

The field number of the array containing the element being removed.

elem_id

The element ID of the element being removed.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_GET

This macro gets the value of a specific array element from the flist. The element remains on the flist unchanged, and the value returned is a pointer to the element flist owned by the flist. The element flist returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the element flist is needed, the application must either make a copy of the returned element flist or use PIN_FLIST_ELEM_TAKE to take ownership of the element from the flist.

Syntax

#include "pcm.h" 
pin_flist_t * 
PIN_FLIST_ELEM_GET(
                 pin_flist_t      *flistp,
                 pin_fld_num_t     fld,
                 int32             elem_id,
                 int32             optional,
                 pin_errbuf_t     *ebufp);

Parameters

flistp

A pointer to the flist containing the array element being obtained.

fld

The field number of the array containing the element being obtained.

elem_id

The ID of the array you need returned.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set, and the element is not found, an error condition is set.

ebufp

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

Return Values

Returns a pointer to the element flist. Returns NULL if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_GET_NEXT

This macro gets an array element from an flist. That is, this macro gets the value of the next element of a specified array on an flist. Lets the application walk the flist, retrieving each element of an array without knowing the element IDs ahead of time.

The element remains on the flist unchanged, and the value returned is a pointer to the element flist owned by the flist. The element flist returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the element flist is needed, the application must either make a copy of the returned element flist or use PIN_FLIST_ELEM_TAKE_NEXT to take ownership of the element from the flist.

Syntax

#include "pcm.h" 
pin_flist_t * 
PIN_FLIST_ELEM_GET_NEXT(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32           *elem_idp,
                 int32            optional,
                 pin_cookie_t    *cookie,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the array element being obtained.

fld

The field number of the array containing the element being taken.

elem_idp

A pointer to the number of the array element being taken.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

cookie

If set to NULL, the first element on the list is returned. Subsequent calls to this macro pass in the cookie, and the next element of the array is retrieved.

ebufp

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

Return Values

Returns a pointer to the element flist, elem_idp, as the element number. Returns NULL if an error occurred or if the element is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_MOVE

This macro moves an element of an array from one flist to another. You can change the field name and record ID when you move the element. The type must remain the same.

Syntax

#include "pcm.h"
int32
PIN_FLIST_ELEM_MOVE(
                 pin_flist_t     *src_flistp,
                 pin_fld_num_t    src_fld,
                 pin_rec_id_t     src_recID,
                 pin_flist_t     *dest_flistp,
                 pin_fld_num_t    dest_fld,
                 pin_rec_id_t     dest_recID,
                 pin_errbuf_t    *ebufp );

Parameters

src_flistp

A pointer to the source flist from which the element is moved.

src_fld

The element that is moved from the source flist.

src_recID

The record ID of the element that is moved.

dest_flistp

A pointer to the destination flist to which an element is moved.

dest_fld

The moved element in the destination flist.

dest_recID

The record ID of the moved element in the destination flist.

ebufp

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

Return Values

Returns 1 if the field to be moved is found. Returns 0 if the field to be moved is not found. Not finding a field does not result in an error buffer error.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_PUT

This macro puts an array element on an flist. The element flist provided is used as the value of the array element. Ownership of the element flist is passed to the target flist, so the application must not destroy it once it has been put. The memory holding the value must be dynamically allocated.

After the value of the field has been added to an flist using this macro, the caller can no longer access the value directly using the pointer to the value. The flist management system may optimize memory usage by moving where the value is stored, so the original pointer is no longer valid.

If the specified array element already exists on the flist, the existing element flist is destroyed and replaced by the new element flist.

If an error condition exists or this macro otherwise fails, the element being put is destroyed. The memory is deallocated and an error is returned to the error buffer.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_ELEM_PUT(
                 pin_flist_t     *flistp,
                 pin_flist_t     *elem_flistp,
                 pin_fld_num_t    fld,
                 int32            elem_id,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the destination flist.

elem_flistp

A pointer to the flist containing the array element being added.

fld

The field number of the array receiving the element.

elem_id

The number of the element being put on the flist.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_SET

This macro sets a copy of an element on an flist. A dynamic copy of the specified element is made for the flist. The element passed in does not have to be in dynamic memory. The element passed in is unaffected by this macro. If the specified element already exists on the flist, the existing element is destroyed and replaced by the new element.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_ELEM_SET(
                 pin_flist_t     *flistp,
                 void            *elem_flistp,
                 pin_fld_num_t    fld,
                 int32            elem_id,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the destination flist for the element.

elem_flistp

A pointer to the flist for the input element.

fld

The field number of the array receiving the element.

elem_id

The number of the element being added.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_TAKE

This macro takes the value of an array element from an flist and removes it from the flist. The dynamically allocated memory holding the element flist is returned to the application. The application is then responsible for freeing this element flist when it is no longer needed. This macro is useful when the array element is no longer needed on the flist after the value is retrieved.

Syntax

#include "pcm.h" 
pin_flist_t * 
PIN_FLIST_ELEM_TAKE(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32            elem_id,
                 int32            optional,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the element being taken.

fld

The field number of the array whose element is being taken.

elem_id

The number of the element being taken.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

ebufp

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

Return Values

Returns a pointer to the element flist. Returns NULL if an error occurred or the element is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_ELEM_TAKE_NEXT

This macro takes the value of the next element of an array from the flist. Lets the application walk the flist, retrieving each element of an array without knowing the element IDs ahead of time.

The element is removed from the flist. The dynamically allocated memory holding the element flist is returned to the application. The application is then responsible for freeing this element flist when it is no longer needed by the application. This macro is useful when the array element will not be needed on the flist after the value is retrieved.

Syntax

#include "pcm.h" 
pin_flist_t * 
PIN_FLIST_ELEM_TAKE_NEXT(
                 pin_flist_t      *flistp,
                 pin_fld_num_t     fld,
                 int32            *elem_idp,
                 int32             optional,
                 pin_cookie_t     *cookie,
                 pin_errbuf_t     *ebufp);

Parameters

flistp

A pointer to the flist of the array containing the element being taken.

fld

The field number of the array containing the element being taken.

elem_idp

A pointer to the number of the element being taken.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

cookie

If set to NULL, the first element on the list is returned. Subsequent calls to this macro pass in the cookie, and the next element of the array is retrieved.

ebufp

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

Return Values

Returns a pointer to the element flist, elem_idp, as the element number. Returns NULL if an error occurred or if the element is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_FLD_COPY

This macro copies a field from one flist to another. If this macro is called to copy an array, it copies the array with all the elements in the array.

You can change the field name while copying the field. The type must remain the same.

Syntax

#include "pcm.h" 
int32
PIN_FLIST_FLD_COPY( 
                 pin_flist_t     *src_flistp,
                 pin_fld_num_t    src_fld,
                 pin_flist_t     *dest_flistp,
                 pin_fld_num_t    dest_fld,
                 pin_errbuf_t    *ebufp);

Parameters

src_flistp

A pointer to the source flist from which the field is copied.

src_fld

The field that is copied from the source flist.

dest_flistp

A pointer to the destination flist to which a field is copied.

dest_fld

The copied field in the destination flist.

ebufp

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

Return Values

Returns 1 if the field to be moved is found. Returns 0 if the field to be moved is not found. Not finding a field does not result in an error buffer error.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_FLD_DROP

This macro removes a field from an flist, destroying the value of the field and reallocating the memory.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_FLD_DROP(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the substructure.

fld

The field number of the substructure being removed.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_FLD_GET

This macro gets the value of a field from an flist. The value returned is a pointer to the actual value owned by the flist, and the field remains on the original flist, unchanged. The value returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the value is needed, the application must either make a copy of the returned value or use PIN_FLIST_FLD_TAKE to take ownership of the field from the flist.

Caution:

The pointer returned is valid only until you modify the flist by setting a field, retrieving a field, or destroying the flist. To ensure that you have a valid pointer, always use PIN_FLIST_FLD_GET immediately before you use the field, or dereference the pointer returned from PIN_FLIST_FLD_GET and store the value locally.

Important:

To copy a field from one flist to another, use PIN_FLIST_FLD_COPY instead of PIN_FLIST_FLD_GET and PIN_FLIST_FLD_SET. To copy an element from one flist to another, use PIN_FLIST_ELEM_COPY.

Syntax

#include "pcm.h" 
void * 
PIN_FLIST_FLD_GET(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32            optional,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the field being obtained.

fld

The number of the field being obtained.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

ebufp

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

Return Values

Returns a pointer to the value on the flist. The pointer must be cast appropriately depending on the type of the field. Returns NULL if an error occurred or if the field is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_FLD_MOVE

This macro moves a field from one flist to another. If this macro is called to move an array, it moves the array with all the elements in the array.

You can change the field name while moving the field. The type must remain the same.

Syntax

#include "pcm.h" 
int32
PIN_FLIST_FLD_MOVE( 
                 pin_flist_t     *src_flistp,
                 pin_fld_num_t    src_fld,
                 pin_flist_t     *dest_flistp,
                 pin_fld_num_t    dest_fld,
                 pin_errbuf_t    *ebufp );

Parameters

src_flistp

A pointer to the source flist from which a field is moved.

src_fld

The field that is moved from the source flist.

dest_flistp

A pointer to the destination flist into which a field is moved.

dest_fld

The moved field in the destination flist.

ebufp

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

Return Values

Returns 1 if the field to be moved is found. Returns 0 if the field to be moved is not found. Not finding a field does not result in an error buffer error.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_FLD_PUT

This macro puts a field (including its data value) in an flist. The memory holding the value must be dynamically allocated. The dynamic memory holding the value is given to the flist as part of the put. This is useful for adding a field to the flist without copying its value, if that memory is no longer needed by the application.

Important:

To move fields between flists or to rename fields, use PIN_FLIST_FLD_MOVE, PIN_FLIST_ELEM_MOVE, and PIN_FLIST_FLD_RENAME instead of PIN_FLIST_FLD_TAKE and PIN_FLIST_FLD_PUT.

After the value of the field has been added to an flist using this macro, the caller can no longer access the value directly using the pointer to the value. The flist management system may optimize memory usage by moving where the value is stored, so the original pointer is no longer valid.

If the specified field already exists in the flist, the previous value is destroyed and replaced by the new value.

If an error condition exists or this macro otherwise fails, the field being put is destroyed. The memory is deallocated and an error is returned to the error buffer.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_FLD_PUT(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 void            *valp,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist receiving the field.

fld

The number of the field being added.

valp

A pointer to the field value being added.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_FLD_RENAME

This macro changes the name of a field in an flist. If you are changing the name of an array, this macro changes the names of all the elements in the array.

The type of the fields must be the same.

Syntax

#include "pcm.h" 
void
PIN_FLIST_FLD_RENAME(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    src_fld,
                 pin_fld_num_t    dest_fld,
                 pin_errbuf_t    *ebufp)

Parameters

flistp

A pointer to the flist in which a field is renamed.

src_fld

The field that is renamed.

dest_fld

The new name of the field.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

If the field is not found, the error buffer contains a PIN_ERR_NOT_FOUND error.

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_FLD_SET

This macro adds a field and a value to an flist. A dynamic copy of the specified value is made for the flist. The value passed does not have to be in dynamic memory. The value passed is unaffected by the macro.

If the specified field already exists in the flist, the existing value is destroyed and replaced by the new value.

Important:

To copy a field from one flist to another, use PIN_FLIST_FLD_COPY instead of PIN_FLIST_FLD_GET and PIN_FLIST_FLD_SET. To copy an element from one flist to another, use PIN_FLIST_ELEM_COPY.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_FLD_SET(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 void            *valp,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist receiving the field.

fld

The number of the field being added.

valp

A pointer to the field value.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_FLD_TAKE

This macro takes a field from an flist and returns its value. The dynamically allocated memory holding the field value is returned to the application. The application is then responsible for freeing this memory when it is no longer needed. This macro is useful when fields will not be needed after the field value is retrieved.

Caution:

If you use PIN_FLIST_FLD_GET, you should do so before using this macro. PIN_FLD_FLIST_TAKE can modify the memory locations of the flist, making the PIN_FLIST_FLD_GET pointer invalid. To ensure that the pointer to the flist remains valid, always call PIN_FLIST_FLD_GET immediately before using the field.

Use PIN_FLIST_FLD_GET when a read-only pointer to the field is needed.

Important:

To move fields between flists or to rename fields, use PIN_FLIST_FLD_MOVE, PIN_FLIST_ELEM_MOVE, and PIN_FLIST_FLD_RENAME instead of PIN_FLIST_FLD_TAKE and PIN_FLIST_FLD_PUT.

Syntax

#include "pcm.h" 
void * 
PIN_FLIST_FLD_TAKE(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32            optional,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the field being taken.

fld

The number of the field being taken.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

ebufp

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

Return Values

Returns a pointer to the field's value. The pointer must be cast appropriately depending on the type of field. Returns NULL if an error occurred or if the field is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SUBSTR_ADD

This macro adds a substructure to an flist. The flist for the substructure is created and returned. The pointer to this substruct flist can then be used to set/put fields into the substructure. If the substructure already exists on the flist, the existing substruct flist is destroyed and replaced by the new substruct flist.

Syntax

#include "pcm.h" 
pin_flist_t * 
PIN_FLIST_SUBSTR_ADD(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist receiving the substructure.

fld

The field number of the substructure being added.

ebufp

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

Return Values

Returns a pointer to the flist for the substructure. Returns NULL if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SUBSTR_DROP

This macro removes a substructure from an flist, freeing the allocated memory.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_SUBSTR_DROP(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the substructure being dropped.

fld

The field number of the substructure being dropped.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SUBSTR_GET

This macro gets a substructure from an flist. The substructure remains on the flist unchanged, and the value returned is a pointer to the substructure flist, owned by the flist. The substructure returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the substructure flist is needed, the application must either make a copy of the returned substructure flist or use the PIN_FLIST_SUBSTR_TAKE macro to take ownership of the substructure.

Syntax

#include "pcm.h" 
void * 
PIN_FLIST_SUBSTR_GET(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32            optional,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist with the substructure being obtained.

fld

The field number of the substructure being obtained.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

ebufp

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

Return Values

Returns a pointer to the substructure flist. Returns NULL if an error occurred or if the element is not found.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SUBSTR_PUT

This macro puts a substructure on an flist. The substructure flist provided is used as the value of the substructure. Ownership of the substructure flist is passed to the target flist, so the application must not destroy it once it has been put. The memory holding the value must be dynamically allocated.

After the value of the field has been added to an flist using this macro, the caller can no longer access the value directly using the pointer to the value. The flist management system may optimize memory usage by moving where the value is stored, so the original pointer is no longer valid.

If the specified substructure already exists on the target flist, the existing element is destroyed and replaced by the new element.

If an error condition exists or the macro otherwise fails, the substructure being put is destroyed. The memory is deallocated and an error is returned to the error buffer.

This macro is optimal for adding inordinately large chunks of data to an flist. The flist does not allocate memory for the added data; it is merely linked to where the memory is already dynamically allocated. In contrast, PIN_FLIST_SUBSTR_SET adds an element by reallocating memory for it in the flist.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_SUBSTR_PUT(
                 pin_flist_t     *flistp,
                 void            *substr_flistp,
                 pin_fld_num_t    fld,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist being added.

substr_flistp

A pointer to the flist containing the substructure being added.

fld

The field number of the substructure being added.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SUBSTR_SET

This macro adds a copy of a substructure to an flist. A dynamic copy of the specified substructure is made for the flist. The substructure passed in does not have to be in dynamic memory. The substructure passed in is unaffected by this macro. If the specified field already exists on the flist, the existing substructure is destroyed and replaced by the new substructure.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_SUBSTR_SET(
                 pin_flist_t     *flistp,
                 void            *substr_flistp,
                 pin_fld_num_t    fld,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist receiving the substructure.

substr_flistp

A pointer to the flist containing the substructure being added.

fld

The field number of the substructure being added.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SUBSTR_TAKE

This macro takes a substructure off of an flist and returns its value. The dynamically allocated memory holding the field value is returned to the application. The application is then responsible for freeing this memory when it is no longer needed. This macro is useful when fields will not be needed after the field value is retrieved.

Syntax

#include "pcm.h" 
void * 
PIN_FLIST_SUBSTR_TAKE(
                 pin_flist_t     *flistp,
                 pin_fld_num_t    fld,
                 int32            optional,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A pointer to the flist containing the substructure being taken.

fld

The field number of the substructure being removed from flistp.

optional

If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Flist Management Macros

This section describes flist management macros.

PIN_FLIST_CONCAT

This BRM 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.

Syntax

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

Parameters

dest_flistp

A pointer to the destination flist.

src_flistp

A pointer to the source flist.

ebufp

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

Return Values

Returns the concatenated flist in dest_flistp. If src_flistp is NULL, dest_flistp is returned unchanged. Returns an error in the error buffer if dest_flistp is NULL.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_COPY

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

Syntax

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

Parameters

flistp

A pointer to the flist to be copied.

ebufp

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

Return Values

Returns a pointer to the new flist. Returns NULL if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_COUNT

This macro counts the number of fields on the flist. Only fields on the main flist are included. Each array element and substruct is 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 are counted.

Syntax

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

Parameters

flistp

A pointer to an flist to count the fields of.

ebufp

A 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 0 if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_CREATE

This BRM macro creates an flist that is used to pass parameters to the PCM_OP function. This macro 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.

Syntax

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

Parameter

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*. Returns NULL if an error occurred.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_DESTROY

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

PIN_FLIST_DESTROY can destroy an flist, even if the error buffer is NULL.

Syntax

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

Parameters

*flistp

A pointer to the flist to destroy.

*ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_DESTROY_EX

This macro destroys an flist. Flists use dynamically allocated memory, and they must be destroyed to free that memory. This macro first checks whether the pointer passed in is NULL. If the pointer is NULL, it returns. If the pointer is not NULL, 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 error buffer is NULL.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_DESTROY_EX(
                 pin_flist_t     **flistpp,
                 pin_errbuf_t     *ebufp);

Parameters

**flistpp

A pointer to the flist to destroy.

*ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_PRINT

This macro prints, in ASCII format, an flist to a file. 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.

Syntax

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

Parameters

flistp

A 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

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Example

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_FLIST_SORT

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 sort_parameter, called PIN_FLD_RESULTS. It would look like:

PIN_FLD_RESULTS
        field 1
        field 2
         .
         .
         .
  

Then use sort_default to compare nonexistent fields to existing fields. If all of the result elements have field values, 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.

Syntax

#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

A 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 macro, pass the exact array (flist) you want sorted, not the entire array.

sort_listp

A 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

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_SORT_REVERSE

This macro sorts flists in reverse order. This macro, 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 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 nonexistent fields to existing fields. If all of the result elements have field values, 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.

Syntax

#include "pcm.h" 
void 
PIN_FLIST_SORT_REVERSE(
                 pin_flist_t     *flistp,
                 pin_flist_t     *sort_listp,
                 int32            sort_default,
                 pin_errbuf_t    *ebufp);

Parameters

flistp

A 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

A 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

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_STR_TO_FLIST

This macro takes a string representation of an flist (for example, the output of PIN_FLIST_TO_STR) and creates an flist run-time data structure.

Syntax

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

Parameters

str

A 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", the database number in this parameter will replace it.

flistp

A pointer to a buffer for the return flist.

ebufp

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

Return Values

Returns the string in flistp.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_TO_STR

This macro prints, in ASCII format, the contents of an flist to a buffer.

Syntax

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

Parameters

flistp

A 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, including the \0.

ebufp

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

Return Values

Returns the string in strpp. If a buffer was allocated, len is the size of the string, including the NULL terminator. If a buffer is allocated, the application owns the memory and must free it eventually.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_TO_STR_COMPACT_BINARY

This macro prints, in compact binary form, the contents of an flist to a buffer.

Syntax

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

Parameters

flistp

A 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, including the \0.

ebufp

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

Return Values

Returns the string in strpp. The string is stored in binary format in compact form, which means the field numbers, instead of the field names, are stored in the buffer. If a buffer was allocated, len is the size of the string, including the NULL terminator. If a buffer is allocated, the application owns the memory and must free it eventually.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_FLIST_TO_XML

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 does not convert data in buffer fields or fields of type PIN_FLDT_BINSTR.

Note:

This macro does not generate a .DTD file.

Syntax

#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

A 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 do not specify this field, the default root element name, document, is used.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only 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 and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

POID Management Macros

This section describes POID management macros.

PIN_POID_COMPARE

This BRM macro compares two POIDs for equality. All fields of the POIDs, including the revision level, must be identical for them to be considered equal.

Syntax

#include "pcm.h" 
int32 
PIN_POID_COMPARE(
               poid_t           *poidp1,
               poid_t           *poidp2,
               int32             check_rev,
               pin_errbuf_t     *ebufp);

Parameters

poidp1

A pointer to the first POID to be compared.

poidp2

A pointer to the second POID to be compared.

check_rev

Determines whether or not the revision level of two POIDs is compared. If check_rev is set to 0, only the POID ID, database number, and type are compared. If check_rev is set to a non-zero value, the POID ID, database number, type, and revision number are compared.

ebufp

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

Return Values

Returns 0 if the POIDs are identical. Returns a negative value if poidp1 is less than poidp2. Returns a positive value if poidp1 is greater than poidp2.

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_COPY

This macro copies a POID. The new POID uses dynamically allocated memory and is owned by the caller.

If src_poidp is NULL, or if the source POID data type is NULL, a NULL value is returned, and no error condition is set.

Syntax

#include "pcm.h" 
poid_t* 
PIN_POID_COPY(
               poid_t           *src_poidp,
               pin_errbuf_t     *ebufp);

Parameters

src_poidp

A pointer to the source POID.

ebufp

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

Return Values

Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.

Success codes

PCM_ERR_NONE

Error codes

PCM_ERR_NO_MEM

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_CREATE

This macro creates a POID. The POID uses dynamically allocated memory, and ownership of the POID is given to the caller. A copy is made of type, so it does not need to be in dynamic memory when passed.

id is typically initialized as 0. The create operation finds the next available ID in the database and uses it when creating the object.

A source POID with a type of NULL is handled correctly. See the "Portal Object ID (POID)" in BRM Developer's Guide for more information on POIDs.

Syntax

#include "pcm.h" 
poid_t* 
PIN_POID_CREATE(
               int64             db,
               char             *type,
               int64             id,
               pin_errbuf_t     *ebufp);

Parameters

db

The database number.

type

The data type for the new POID. See the list of objects in "Storable Class Definitions". Examples are /service and /event/customer/nameinfo.

id

A unique object ID. This is a 64-bit quantity, so an extremely large number of objects can exist within a single database. Object IDs are unique within a single database, but not across databases.

ebufp

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

Return Values

Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Examples

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_POID_DESTROY

This macro destroys a POID. POIDs use dynamically allocated memory and must be destroyed to free that memory. The entire POID is destroyed, including the type string.

Syntax

#include "pcm.h" 
void 
PIN_POID_DESTROY(
               poid_t           *poidp,
               pin_errbuf_t     *ebufp);

Parameters

poidp

A pointer to the POID to be destroyed.

ebufp

A pointer to an error buffer. Used to pass status information back to the caller. This parameter is optional. If a NULL is passed in, no error information is returned.

Return Values

This macro returns nothing.

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

Examples

The sample_app.c file and the accompanying makefile illustrate how to use this macro when setting up a generic BRM account and service. The files are located in BRM_SDK_Home/source/samples/app/c.

PIN_POID_FROM_STR

This macro converts a string to a POID.

Note:

This macro allocates the new POID's memory. To avoid memory leaks, PUT the POID onto an flist (typical case) or destroy the flist.

Syntax

#include "pcm.h" 
poid_t* 
PIN_POID_FROM_STR(
               char             *strp,
               char            **endcpp,
               pin_errbuf_t     *ebufp);

Parameters

strp

A pointer to the destination string.

endcpp

A pointer to the character following the last character of the POID value. That is, the character that terminated the scan (usually NULL, white space, or a new line).

ebufp

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

Return Values

Returns a pointer to the POID created from the input string if the macro is successful. Returns NULL if the macro fails.

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_GET_DB

This macro returns the database number portion of a POID.

Syntax

#include "pcm.h"
int64
PIN_POID_GET_DB(
               poid_t     *poidp);

Parameter

poidp

A pointer to the POID whose database number is being returned.

Return Values

Returns the database number if the macro is successful.

Error Handling

This macro does not handle errors.

PIN_POID_GET_ID

This macro returns a POID's ID.

Syntax

#include "pcm.h"
int64
PIN_POID_GET_ID(
               poid_t     *poidp);

Parameter

poidp

A pointer to the POID whose ID is being returned.

Return Values

Returns the POID's ID if the macro is successful.

Error Handling

This macro does not handle errors.

PIN_POID_GET_REV

This macro returns the POID's revision level. The revision level is incremented each time any portion of the object is updated.

Syntax

#include "pcm.h"
int32
PIN_POID_GET_REV(
               poid_t     *poidp); 

Parameter

poidp

A pointer to the POID whose non-zero revision level is being returned.

Return Values

Returns the POID's revision level if the macro is successful.

Error Handling

This macro does not handle errors.

PIN_POID_GET_TYPE

This macro returns the object type of the POID in string format. Possible types are listed in "Storable Class Definitions". Examples are /account and /event/billing/charge.

Syntax

#include "pcm.h"
char*
PIN_POID_GET_TYPE(
               poid_t     *poidp); 

Parameter

poidp

A pointer to the POID whose type is being returned.

Return Values

Returns the POID's type as a string if the macro is successful.

Error Handling

This macro does not handle errors.

PIN_POID_IS_NULL

This macro checks a POID to see whether it is NULL. The condition is satisfied if the pointer is NULL or the database number is 0.

Syntax

#include "pcm.h" 
int32 
PIN_POID_IS_NULL(
               poid_t     *poidp);

Parameter

poidp

A pointer to the POID to check.

Return Values

Returns a non-zero value if the POID pointer is NULL or the database number is 0.

Error Handling

This macro does not handle errors.

PIN_POID_LIST_ADD_POID

This macro adds a POID to the POID list.

Syntax

#include "pcm.h"
void
PIN_POID_LIST_ADD_POID( 
                       char           **strpp,
                       poid_t         *pdp, 
                       int32          flag, 
                        pin_errbuf_t   *ebufp) 

Parameters

strpp

Pointer to the POID list.

pdp

Pointer to the POID to be added to the list.

flag

A PCM flag (PCM_FLDFLG_FIFO or PCM_FLDFLG_CMPREV).

ebufp

Pointer to the error buffer.

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_COPY

This macro copies a POID list.

Syntax

#include "pcm.h"
poid_list_t * 
PIN_POID_LIST_COPY(
                   poid_list_t  *src_pldp, 
                    pin_errbuf_t  *ebufp) 

Parameters

src_pldp

Pointer to the POID list to be copied.

ebuf

Pointer to the error buffer.

Return Values

Returns a pointer to the newly created POID list if the macro is successful. Returns NULL if the macro fails.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_COPY_NEXT_POID

This macro copies 'next' POID from the POID list.

Syntax

#include "pcm.h" 
poid_t * 
pin_poid_list_get_next( 
                       char            *strp, 
                       int32           optional, 
                       pin_cookie_t    *cookiep, 
                        pin_errbuf_t    *ebufp) 

Parameters

strp

Pointer to the POID list from which the next POID is to be copied.

optional

If this flag is set to a non-zero value and the element is not found, no error condition is set. If this flag is not set, and the element is not found, an error condition is set.

cookiep

The cookie for the next POID.

ebufp

Pointer to the error buffer.

Return Values

Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_COPY_POID

This macro copies the specified POID from the POID list.

Syntax

#include "pcm.h" 
poid_t* 
PIN_POID_LIST_COPY_POID(
                        char            *strp, 
                        void            *vp, 
                        int32           flags, 
                         pin_errbuf_t    *ebufp) 

Parameters

strpp

Pointer to the POID list.

vp

Pointer to the POID to be copied.

flags

A PCM flag (PCM_FLDFLG_CMPREV or PCM_FLDFLG_TYPE_ONLY) to check for the existence of the POID to be copied.

Ebufp

Pointer to the error buffer.

Return Values

Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_CREATE

This macro creates a POID list.

Syntax

#include "pcm.h" 
poid_list_t * 
PIN_POID_LIST_CREATE(
                      pin_errbuf_t *ebufp) 

Parameter

ebufp

Pointer to the error buffer.

Return Values

Returns a pointer to the newly created POID list if macro is successful. Returns NULL if the macro fails.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_DESTROY

This macro frees a POID list.

Syntax

#include "pcm.h" 
void 
PIN_POID_LIST_DESTROY(
                      poid_list_t *pldp, 
                        pin_errbuf_t *ebufp) 

Parameters

pldp

Pointer to the POID list to be freed.

ebufp

Pointer to the error buffer.

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_REMOVE_POID

This macro removes a POID from the POID list.

Syntax

#include "pcm.h" 
void 
PIN_POID_LIST_REMOVE_POID(
                          char        **strpp, 
                          poid_t      *pdp,  
                          int32       check_rev, 
                            pin_errbuf_t *ebufp) 

Parameters

strpp

Pointer to the POID list.

pdp

Pointer to the POID to be removed from the list.

check_rev

Determines the existence of the POID to be removed. If check_rev is set to 0, existence of the POID is checked.

ebufp

Pointer to the error buffer.

Return Values

This macro returns nothing.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_LIST_TAKE_NEXT_POID

This macro takes the 'next' POID from the POID list.

Syntax

#include "pcm.h" 
poid_t * 
pin_poid_list_take_next( 
                        char            **strpp, 
                        int32           optional,
                           pin_errbuf_t    *ebufp) 

Parameters

strpp

Pointer to the POID list.

optional

If this flag is set to a non-zero value and the element is not found, no error condition is set. If this flag is not set, and the element is not found, an error condition is set.

ebufp

Pointer to the error buffer.

Return Values

Returns a pointer to the POID taken from the POID list if the macro is successful. Returns NULL if the macro fails.

Error Handling

This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_PRINT

This macro prints a POID.

Syntax

#include "pcm.h" 
void 
PIN_POID_PRINT(
               poid_t           *poidp,
               FILE             *fi,
               pin_errbuf_t     *ebufp);

Parameters

poidp

A pointer to the POID to print.

fi

The FILE pointer to the file to receive the message. If the value of FILE is NULL, the message is printed to stdout.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

PIN_POID_TO_STR

This macro prints a POID to a string. Put the info of a POID into a string (strpp). If the buffer (ebufp) is not large enough to hold the string, PIN_ERR_BAD_ARG is returned. The return value of lenp includes the \0. The format of the string is:

"%d %s %d %d"

where the values are for:

database_number object_type object_id object_revision_level

object_revision_level is incremented each time the object is updated.

Syntax

#include "pcm.h" 
void 
PIN_POID_TO_STR(
               poid_t           *poidp,
               char            **strpp,
               int32            *lenp,
               pin_errbuf_t     *ebufp);

Parameters

poidp

A pointer to the POID to be printed.

strpp

A pointer to the buffer receiving the string version of the POID. This should be 48 larger that the value of PCM_MAX_POID_TYPE, to accommodate the largest strings.

lenp

The length of the buffer.

ebufp

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

Return Values

This macro returns nothing.

Error Handling

This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only 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 and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.

String Manipulation Functions

This section describes string manipulation functions.

About the String Manipulation Functions

You use the string manipulation functions to store and retrieve server strings, such as reason codes, help messages, and other text displayed in the user interface. These strings are stored on the server so that they can be easily localized for multiple languages and displayed simultaneously in the appropriate languages for the client locales. For example, French and German customer service representatives (CSRs) logged into BRM at the same time can read messages in their own languages.

String manipulation functions also allow data received by the database to be canonicalized for easy processing.

BRM Locale IDs

UNIX, Windows, and Java use different locale IDs. So BRM includes a locale table, which maps the BRM locale to locale strings for various platforms.

Similar to UNIX, the BRM locale is either:

  • The two-character ISO code for the language. These two-character locales are used for a language in its country of origin. For example, fr designates French used in France.

  • A concatenation of the two-character ISO code for the language and the two-character ISO code for the country. For example, en_US designates English in the United States.

The locale description IDs are mapped to a /strings table containing the textual description of the supported locales. This table and the BRM table name are stored in the database under /config/locales.

For more information on BRM locale names, see "Locale Names" in BRM Developer's Guide.

Storable Class Hierarchy for Localized Strings

BRM includes a /strings storable class to store localized strings.

Note:

You cannot extend the /strings storable class.

Structure of the /strings storable class:

/strings
POID PIN_FLD_POID
TIMESTAMP PIN_FLD_CREATED_T
TIMESTAMP PIN_FLD_MOD_T
STRING PIN_FLD_DOMAIN             required, length = 1023
STRING PIN_FLD_DESCR              optional, length = 1023
STRING PIN_FLD_LOCALE             required, length = 1023
INT PIN_FLD_STRING_ID             required
INT PIN_FLD_STR_VERSION           required
STRING PIN_FLD_STRING             required, length = 1023
STRING PIN_FLD_HELP_STRING        optional, length = 1023
  

For descriptions of the fields, see the /strings storable class description.

Important:

Do not change these names and numbers or the information will not be accessible.

Locale Mapping

For detailed information on BRM locale mapping, see "Locale Names" in BRM Developer's Guide.

Localized String Data Files

A file of localized string data contains multibyte character set (MBCS) strings, and the data is loaded into the database by running a utility that constructs storable string objects using information in the file.

The file extension of the file must be the BRM locale ID.

Sample names for files containing localized string data:

  • locale_descr.en_US contains locale description information for United States English.

  • reasons.en_US contains all of the reason code data for United States English.

String File Format Description

This section describes the required format of the string file. To use this file with the related functions and utilities, the file must follow this format.

Note:

The load utility parser is case-insensitive to the keywords. It passes the locale and domain strings to the database as received. BRM is case sensitive. For example, en_us and the BRM locale en_US are not considered the same, nor are "Reason Codes-Credit Reasons" and "reason codes-credit reasons."
  • Comments begin with the # symbol. All comments and white space are ignored.

  • The string file has a locale ID as the first noncommented statement of the file, and there is only one locale ID per file. You can use existing domains in the files and/or add your own. Organize your strings by domains within the file.

  • The string object definition is bounded by STR-END and consists of an ID unique within a domain, a string version, and the string itself.

  • A string is delimited by quotation marks and can contain any character, including a quotation mark if escaped (\"). The percent symbol followed by an integer (%1) is interpreted as a substitution parameter flag.

  • For reason codes, the version field specifies the domain of the reason, such as credit or debit.

This example shows a compatible string file:

#######################
# strings.en_US
#######################
  
LOCALE = "en_US" ;
  
DOMAIN = "Reason Codes-Credit Reasons" ;
STR
     ID = 1 ;
     VERSION = 1 ;
     STRING = "Customer not satisfied with service" ;
END
STR
     ID = 2 ;
     VERSION = 1 ;
     STRING = "Customer unaware of charges" ;
END
STR
     ID = 3 ;
     VERSION = 1 ;
     STRING = "Debited account by mistake" ;
END
  
DOMAIN = "Reason Codes-Debit Reasons" ;
STR
     ID = 1 ;
     VERSION = 1 ;
     STRING = "Technical and support charges" ;
END
STR
     ID = 2 ;
     VERSION = 1 ;
     STRING = "Service charges" ;
END
STR
     ID = 3 ;
     VERSION = 1 ;
     STRING = "Credited account by mistake" ;
END

String Manipulation Example

You can create message strings in multiple languages to obtain all the reason codes for English.

This is an example definition:

string_list_t*
pcm_get_localized_string_list(
               pcm_context_t     *context_p,
               const char        *locale_p,
               const char        *domain_p,
               const int32        string_id,
               const int32        string_vers,
               pin_errbuf_t      *ebufp);
  

The top-level function, pcm_get_localized_string_list, allows arbitrary queries on the /strings table. The argument list is similar to pcm_get_localized_string except that message buffers are not supplied by the caller. The function can accept a null locale string, a null domain string, a string ID = -1, or a string version = -1 to indicate that the argument is not part of the search.

This example shows retrieving strings:

pcm_get_localized_string_list(context_p,"en_US","Reason Codes-Active Status Reasons",-1,1,ebufp);
  

is equivalent to:

select*
from strings_t
where locale = "en_US" AND
     domain = "Reason Codes-Active Status Reasons" AND
     string_vers = 1
  

which returns a set of string objects for any locale ID fitting these criteria. The function returns a container object of type string_list_t.

String Manipulation Functions

Table 2-5 lists String Manipulation Functions.

Table 2-5 String Manipulation Functions

Function Description

pcm_get_localized_string_list

Retrieves the specified string list to be used by the string manipulation functions.

pin_string_list_destroy

Deallocates the object and its flist when finished with the string list.

pin_string_list_get_next

Retrieves the next object in the string list.


pcm_get_localized_string_list

This function retrieves the specified string list to be used by the string manipulation functions.

Use this function to obtain a group of related strings. It is much more efficient than calling pcm_get_error_message for each individual string.

pin_string_list_destroy

This function deallocates the object and its flist when finished with the string list.

Important:

To prevent memory leaks, you must call this after calling pcm_get_string_list.

Syntax

void
pin_string_list_destroy(
               string_list_t     *string_listp,
               pin_errbuf_t      *ebufp);

Parameters

string_listp

A pointer to the list.

ebufp

A pointer to an error buffer. Passes status information back to the caller.

pin_string_list_get_next

This function retrieves the next object in the string list.

The caller passes in the string list and a string info object, and the attributes of the next string object are pulled from the list and copied to the string info object. The info object is then returned to the caller. This function calls pin_string_info_init internally to flush the string info object and prepare it for new data. This allows the same string info object to be used repeatedly when iterating through the list.

Syntax

string_info_t*
pin_string_list_get_next(
               string_list_t     *string_listp,
               string_info_t     *string_infop,
               pin_errbuf_t      *ebufp);

Parameters

string_listp

A pointer to the list.

string_infop

A pointer to the string.

ebufp

A pointer to an error buffer. Passes status information back to the caller.

Validity Period Manipulation Macros

Validity period manipulation macros are used to get and set relative offset values for validity periods that start and end after a relative period passes. For example, a product's cycle fee period can become effective three months after the product is purchased.

About Relative Offset Values

Relative validity period information is stored in the BRM database in DETAILS fields. There are DETAILS fields for product, discount, and resource-balance validity periods. The specific name of the fields vary, but all end with "_DETAILS".

Relative validity period information includes the following values:

  • Mode - Specifies generally when the validity period starts or ends and can be one of these:

    • PIN_VALIDITY_ABSOLUTE = 0

    • PIN_VALIDITY_IMMEDIATE = 1

    • PIN_VALIDITY_NEVER = 2

    • PIN_VALIDITY_FIRST_USAGE = 3

    • PIN_VALIDITY_RELATIVE = 4

  • Unit - Specifies the type of offset unit, which can be one of these:

    • Seconds = 1

    • Minutes = 2

    • Hours = 3

    • Days = 4

    • Months = 5

    • Event cycles = 7

    • Accounting cycles = 8

    • Billing cycles = 9

    • None = 0

  • Offset - Specifies the number of units in the offset period.

    Note:

    Not all of the unit and mode values listed above can be used with every relative validity period in BRM. The unit and mode you can specify depends on the validity period you're setting and whether you're setting the start or end time. For more information, see the following topics:

PIN_VALIDITY_GET_UNIT

This macro retrieves the relative offset unit from the start- or end-time details value that is passed in.

Syntax

#include "pcm.h" 
u_int32
PIN_VALIDITY_GET_UNIT(
                 u_int32     encoded_value);

Parameter

encoded_value

The encoded value of the start- or end-time details field.

Return Values

Returns the value of the relative offset unit.

PIN_VALIDITY_GET_OFFSET

This macro retrieves the relative offset (the number of units in the relative period) from the start- or end-time details value that is passed in.

Syntax

#include "pcm.h" 
u_int32
PIN_VALIDITY_GET_OFFSET(
                 u_int32     encoded_value);

Parameter

encoded_value

The encoded value of the start- or end-time details field.

Return Values

Returns the value of the relative offset.

PIN_VALIDITY_GET_MODE

This macro retrieves the mode value from the start- or end-time details value that is passed in.

Syntax

#include "pcm.h" 
pin_validity_modes_t
PIN_VALIDITY_GET_MODE(
                 u_int32     encoded_value);

Parameter

encoded_value

The encoded value of the start- or end-time details field.

Return Values

Returns the value of the relative mode.

PIN_VALIDITY_SET_UNIT

This macro sets the relative offset unit in the start- or end-time details value that is passed in.

Syntax

#include "pcm.h" 
u_int32
PIN_VALIDITY_SET_UNIT(
                 u_int32      encoded_value,
                  u_int32      unit_value);

Parameters

encoded_value

The encoded value of the start- or end-time details field.

unit_value

The offset unit value to set.

Return Values

Returns the encoded value of the start- or end-time details field set with the unit value passed in.

PIN_VALIDITY_SET_OFFSET

This macro sets the relative offset (number of offset units) in the start- or end-time details value that is passed in.

Syntax

#include "pcm.h" 
u_int32
PIN_VALIDITY_SET_OFFSET(
                u_int32     encoded_value,
                 u_int32          offset_value);

Parameters

encoded_value

The encoded value of the start- or end-time details field.

offset_value

The offset value to set.

Return Values

Returns the encoded value of the start- or end-time details field set with the offset value passed in.

PIN_VALIDITY_SET_MODE

This macro sets the relative mode in the start- or end-time details value passed in.

Syntax

#include "pcm.h" 
u_int32
PIN_VALIDITY_SET_MODE(
                u_int32     encoded_value,
                 pin_validity_modes_t     mode_value);

Parameters

encoded_value

The encoded value of the start- or end-time details field.

mode_value

The mode value to set.

Return Values

Returns the encoded value of the start- or end-time details field set with the mode value passed in.

PIN_VALIDITY_DECODE_FIELD

This macro decodes the values of the mode, unit, and offset in the start- or end-time details value passed in and then sets them in mode, unit, and offset variables.

Syntax

#include "pcm.h" 
void
PIN_VALIDITY_DECODE_FIELD(
                u_int32                   encoded_value,
                pin_validity_modes_t    mode_variable,
                u_int32                   unit_variable,
                 u_int32                   offset_variable);

Parameters

encoded_value

The encoded value of the start- or end-time details field.

mode_variable

The mode variable to set.

unit_variable

The unit variable to set.

offset_variable

The offset variable to set.

Return Values

This macro returns nothing.

PIN_VALIDITY_ENCODE_FIELD

This macro takes the mode, unit, and offset values passed in and encodes them into a start- or end-time details field value.

Syntax

#include "pcm.h" 
u_int32
PIN_VALIDITY_ENCODE_FIELD(
                 pin_validity_modes_t    mode_value,
                 u_int32                   unit_value,
                  u_int32                   offset_value);

Parameters

mode_value

The mode value.

unit_value

The unit value.

offset_value

The offset value.

Return Values

Returns the encoded value of the start- or end-time details field, set with the mode, unit, and offset values passed in.