1 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 object by using the regular free routine when you are finished.
Note:
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
, int32valtype
, 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
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 balance elements from the /config/beid object.
Syntax
#include "pin_errs.h" #include "pcm.h" pin_flist_t* pin_conf_beid( pcm_context_t *ctxp
, pin_errbuf_t *ebufp
);
Parameters
Return Values
Returns values for the /config/beid 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 object by using the regular free routine when you are finished.
Note:
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
, int32valtype
, 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.
Note:
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.
Note:
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 1-1 are defined in pcm.h. They have the same names and functionality as the Java BigDecimal Datatype.
Table 1-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 PDC Creating Product Offerings. |
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 PDC Creating Product Offerings. |
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 nonnegative 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
);
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
);
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
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
);
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
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
);
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_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
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
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( doubled
, 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( doublevalue
, introunding_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 nonnumeric 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
);
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
);
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
);
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
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
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 1-2 contains examples, where x is a pointer pin_decimal_t:
Table 1-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 |
Syntax
pin_decimal_t* pbo_decimal_negate( const pin_decimal_t *pdp
, pin_errbuf_t *ebufp
);
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
);
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
, int32scale
, int32rounding_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
, int32scale
, int32rounding_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
);
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
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
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
);
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
);
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( int32level
, 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( int32level
, 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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( int32level
, 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( int32level
, 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 1-3:
Table 1-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 nonzero value if an error occurred. The only possible failure is the specification of an unreasonable value for level.
Error Handling
Returns a nonzero 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
Return Values
Returns a nonzero value if an error occurred.
Error Handling
Returns a nonzero 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
Return Values
Returns 0 if the macro is successful. Returns a nonzero value if an error occurred. The only possible failure condition is the specification of a NULL pointer.
Error Handling
Returns a nonzero 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
);
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
Return Values
Returns 0 if the error buffer contains no error. Returns a nonzero 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
);
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
, int32location
, int32pin_errclass
, int32pin_err
, int32field
, int32rec_ID
, int32reserved
);
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 1-4:
Table 1-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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, v_int32elem_id
, pin_errbuf_t *ebufp
);
Parameters
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tsrc_fld
, pin_rec_id_tsrc_recID
, pin_flist_t *dest_flistp
, pin_fld_num_tdest_fld
, pin_rec_id_tdest_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, pin_errbuf_t *ebufp
);
Parameters
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
PIN_FLIST_ELEM_DROP
This macro drops the specified array element from an flist. The element flist is destroyed and the memory reallocated.
Note:
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_tfld
, int32elem_id
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32elem_id
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32 *elem_idp
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tsrc_fld
, pin_rec_id_tsrc_recID
, pin_flist_t *dest_flistp
, pin_fld_num_tdest_fld
, pin_rec_id_tdest_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32elem_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32elem_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32elem_id
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32 *elem_idp
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tsrc_fld
, pin_flist_t *dest_flistp
, pin_fld_num_tdest_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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.
Note:
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_tfld
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tsrc_fld
, pin_flist_t *dest_flistp
, pin_fld_num_tdest_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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.
Note:
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_tfld
, void *valp
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tsrc_fld
, pin_fld_num_tdest_fld
, pin_errbuf_t *ebufp
)
Parameters
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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.
Note:
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_tfld
, void *valp
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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.
Note:
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_tfld
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, pin_errbuf_t *ebufp
);
Parameters
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, pin_errbuf_t *ebufp
);
Parameters
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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_tfld
, int32optional
, 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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
);
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
, int32sort_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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
, int32sort_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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
, int64default_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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
, int32flags
, int32encoding
, 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
, int32check_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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 "Portal Object ID (POID)" in BRM Developer's Guide for more information.
Syntax
#include "pcm.h" poid_t* PIN_POID_CREATE( int64db
, char *type
, int64id
, 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
);
Return Values
Returns the database number 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
);
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
);
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
);
Return Values
Returns a nonzero 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
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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)
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 nonzero 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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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)
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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)
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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
Return Values
This macro returns nothing.
Error Handling
This macro uses series-style ebuf error handling. See "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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 "Series-Style ebuf" in BRM Developer's Guide for more information.
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.
Note:
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 int32string_id
, const int32string_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 1-5 lists String Manipulation Functions.
Table 1-5 String Manipulation Functions
Function | Description |
---|---|
Retrieves the specified string list to be used by the string manipulation functions. |
|
Deallocates the object and its flist when finished with the string list. |
|
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.
Note:
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
);
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
);
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 charge offer's cycle fee period can become effective three months after the charge offer is purchased.
About Relative Offset Values
Relative validity period information is stored in the BRM database in DETAILS fields. There are DETAILS fields for charge offer, discount, and 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 are setting and whether you are setting the start or end time. For more information, see the following topics:
-
For information about the relative start and end times of charge offers and discount offers in bundles, see "About the Validity Periods of Offers in Bundles" in BRM PDC Creating Product Offerings.
-
For information about the relative start and end times of discount offers owned by accounts, see "Setting Discount Offer Purchase, Cycle, and Usage Start and End Times" in BRM Managing Customers.
-
For information about the relative start and end times of balances, see "Configuring Validity Periods for Noncurrency Credit Balances" in BRM PDC Creating Product Offerings.
-
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)
;
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)
;
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
);
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_int32encoded_value
, u_int32unit_value
);
Parameters
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_int32encoded_value
, u_int32offset_value
);
Parameters
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_int32encoded_value
, pin_validity_modes_tmode_value
);
Parameters
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_int32encoded_value
, pin_validity_modes_tmode_variable
, u_int32unit_variable
, u_int32offset_variable
);
Parameters
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_tmode_value
, u_int32unit_value
, u_int32offset_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.