This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) Portal Information Network (PIN) libraries.
Use these functions to read configuration files, such as pin.conf files.
This BRM library routine reads a single configuration value from a configuration file.
The Connection Manager (CM), Data Manager (DM), and Portal Communications Module (PCM) libraries all use this routine to read the configuration information.
When first called, this routine looks for the configuration file specific to the application. See "Locations of Configuration and Properties Files" in BRM System Administrator's Guide. The library returns an error if it cannot locate the configuration file.
This routine uses regular malloc. If you are using this routine in a Storage Manager to get data to put on an flist, use SET (not PUT), and then free the storable object by using the regular free routine when you are finished.
Important:
Do not use this routine if performance is a consideration and you use the routine often.For more information on configuration files, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.
For information on reading multiple configuration values from a file, see "pin_conf_multi".
#include "pcm.h"
void
pin_conf(
char *prog_name,
char *token,
int32 valtype,
caddr_t* **valpp,
int32 *errp);
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.
The name of the configuration entry keyword this routine looks for in the configuration file.
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
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.
A pointer to the error buffer, which passes error information back to the caller.
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.
This library routine reads values for BRM resources from the /config/beid storable object.
#include "pin_errs.h"
#include "pcm.h"
pin_flist_t*
pin_conf_beid(
pcm_context_t *ctxp,
pin_errbuf_t *ebufp);
A pointer to an open context. This routine gets the database number from the configuration file of the current application and queries that database for the /config/beid object.
A pointer to the error buffer, which passes error information back to the caller.
This library routine reads multiple configuration values of the same type from a configuration file. To do this, you reuse this routine until it returns PIN_ERR_NOT_FOUND. This routine uses the time_t value to monitor the configuration file for changes throughout this operation and returns an error if the state of the file changes.
The Connection Manager (CM), Data Manager (DM), and PCM libraries all use this routine to read the configuration information.
When first called, this routine looks for the configuration file specific to the application. See "Locations of Configuration and Properties Files" in BRM System Administrator's Guide. The library returns an error if it cannot locate the configuration file.
This routine uses regular malloc. If you are using this routine in a Storage Manager to get data to put on an flist, use SET (not PUT), and then free the storable object by using the regular free routine when you are finished.
Important:
Do not use this routine if performance is a consideration and you use the routine often.For more information on configuration files, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.
For information on reading a single configuration value from a file, see "pin_conf".
#include "pcm.h"
void
pin_conf(
char *prog_name,
char *token,
int32 valtype,
caddr_t* **valpp,
int32 *linep,
time_t *modtp,
int32 *errp);
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.
The name of the configuration entry keyword this routine looks for in the configuration file.
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
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.
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.
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.
A pointer to the error status, which passes error information back to the caller.
This routine returns nothing.
This routine passes error status back to the caller.
If it finds a matching entry in the configuration file, it passes back PIN_ERR_NONE. This indicates that the routine then reuses the key to look for another matching entry (as long as it has not generated a PIN_ERR_STALE_CONF error).
If it does not find a matching entry, it passes back PIN_ERR_NOT_FOUND. This signals the end of the routine.
If it detects, based on a change in the time_t value, that the configuration file has been opened, modified, or has otherwise changed since it first accessed the file (jeopardizing the ability of the routine to maintain correct reference to the last value read), it passes back PIN_ERR_STALE_CONF.
Important:
In this case, you must restart the entire process.The routine may also pass back other error values.
This section describes decimal data type manipulation functions.
The decimal data type application programming interface (API) consists of a minimal set of methods that provides all the functionality you need to perform basic mathematical functions, comparison, and format conversion with the decimal data type. Input and output to the functions are provided using number strings or floating point doubles.
Tip:
Use strings to avoid small quantity errors; for example, 31.299999999 vs. 31.3.If there are errors, functions that return a pin_decimal_t return NULL. pbo_decimal_destroy allows NULL.
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.This section defines the rounding modes that you pass as input parameters in the following functions:
The rounding modes in Table 2-1 are defined in pcm.h. They have the same names and functionality as the Java BigDecimal Datatype.
| Rounding Mode | Description |
|---|---|
|
ROUND_UP |
Rounds up to the nearest number of the appropriate scale. Examples: 21.11 rounds to 21.2 when the scale is one decimal place. |
|
ROUND_DOWN |
Rounds down to the nearest number of the appropriate scale. Examples: 21.19 rounds to 21.1 when the scale is one decimal place. |
|
ROUND_DOWN_ALT |
Rounds down after first rounding to the nearest using a scale of two more than the one configured. This method compensates for possible loss of precision when numbers are rounded down during certain computations, such as when prorating cycle fees. For more information, see "About Rounding Modes That Correct for Loss of Precision" in BRM Setting Up Pricing and Rating. |
|
ROUND_CEILING |
If the number is positive, rounding is the same as for ROUND_UP; if negative, the same as for ROUND_DOWN. |
|
ROUND_FLOOR |
If the number is positive, rounding is the same as for ROUND_DOWN; if negative the same as for ROUND_UP. This method allows you to round to benefit customers. For example, if rounding is set to two significant digits, a credit to a customer of -7.999 is rounded to -8.00, and a debit of 7.999 is rounded to 7.99. |
|
ROUND_FLOOR_ALT |
Rounds using ROUND_FLOOR after first rounding to the nearest using a scale of two more than the one configured. This method compensates for possible loss of precision when numbers are rounded down during certain computations, such as when prorating cycle fees. For more information, see "About Rounding Modes That Correct for Loss of Precision" in BRM Setting Up Pricing and Rating. |
|
ROUND_HALF_UP |
If the discard part is .5 or higher round up; otherwise, round down. Examples: 21.15 rounds to 21.2, 21.14 rounds to 21.1, etc. This is the most common rounding method. |
|
ROUND_HALF_DOWN |
If the discard part is more than .5, round up; if it is .5 or less, round down. Examples: 21.16 rounds to 21.2, 21.15 rounds to 21.1. |
|
ROUND_HALF_EVEN |
If the digit to the left of the discard is odd, rounding is the same as for ROUND_HALF_UP. If the digit to the left is even, rounding is the same as for ROUND_HALF_DOWN. Examples: 1.049 rounds to 1.0 1.050 rounds to 1.0 1.051 rounds to 1.1 1.149 rounds to 1.1 1.150 rounds to 1.2 1.151 rounds to 1.2 |
|
ROUND_UNNECESSARY |
Rounding not allowed. If rounding is attempted with this rounding mode, an error is returned. |
A decimal data type is based on the Java BigDecimal data type. It is an immutable, arbitrary-precision signed decimal number, which consists of an arbitrary precision integer value and a non-negative integer scale, which represents the number of decimal digits to the right of the decimal point.
For this implementation, the scale is set at 15, meaning numbers carry up to 15 decimal places. For operations that would normally result in a value with a larger scale, the value is rounded to 15 decimal places. For example, when multiplying the two decimal data types 12.528694120521357 and 4.126943650923412, the mathematical result would normally be 51.705214655047095455751917310084, which has a scale of 30. However, because the scale is set at 15, the product is rounded to 51.705214655047095 and a consistent scale of 15 is maintained.
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.
This function returns a pointer to a newly allocated pin_decimal_t, which is the absolute value of the input pin_decimal_t.
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.
pin_decimal_t*
pbo_decimal_add(
const pin_decimal_t *pdp1,
const pin_decimal_t *pdp2,
pin_errbuf_t *ebufp);
A pointer to the input pin_decimal_t.
A pointer to another input pin_decimal_t.
A pointer to the error buffer.
This function replaces the value of the first pin_decimal_t with the sum of itself and another pin_decimal_t.
void
pbo_decimal_add_assign(
pin_decimal_t *pdp1,
const pin_decimal_t *pdp2,
pin_errbuf_t *ebufp);
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.
int
pbo_decimal_compare(
const pin_decimal_t *pdp1,
const pin_decimal_t *pdp2,
pin_errbuf_t *ebufp);
A pointer to the first pin_decimal_t.
A pointer to the second pin_decimal_t.
A pointer to the error buffer.
This function makes a copy of the input pin_decimal_t and returns a pointer to the newly allocated pin_decimal_t.
This function frees all the memory associated with the specified pin_decimal_t and sets *decpp to NULL.
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.
pin_decimal_t*
pbo_decimal_divide(
const pin_decimal_t *nump,
const pin_decimal_t *byp,
pin_errbuf_t *ebufp);
A pointer to the dividend.
A pointer to the divisor.
A pointer to the error buffer.
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
This function divides the dividend by the divisor and stores the result in the dividend.
void
pbo_decimal_divide_assign(
pin_decimal_t *nump,
const pin_decimal_t *byp,
pin_errbuf_t *ebufp);
A pointer to the dividend.
A pointer to the divisor.
A pointer to the error buffer.
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
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.The input of type double float (a double-precision floating point number).
A pointer to the error buffer.
See also "pbo_decimal_from_str".
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.
pin_decimal_t*
pbo_decimal_from_double_round(
double value,
int rounding_mode,
pin_errbuf_t *ebufp)
The value to convert.
A pointer to the error buffer.
This function constructs a pin_decimal_t data type from an input string and returns a pointer to the newly created pin_decimal_t data type.
This function understands NULL to create a NULL-valued pin_decimal_t. The string does not need to end with a null character, but parsing will end at either a null character or any white space character.
This function ignores leading spaces, tabs, and leading 0's and checks on non-numeric types.
This function detects the sign (+ or -) and stores it. This function accepts the same input at strtod except that an exponent is not allowed, and only base 10 is supported.
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
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.
This function multiplies the two input pin_decimal_t values and returns a pointer to a new pin_decimal_t that is the product.
pin_decimal_t*
pbo_decimal_multiply(
const pin_decimal_t *pdp1,
const pin_decimal_t *pdp2,
pin_errbuf_t *ebufp);
The pointer to an input pin_decimal_t.
The pointer to another input pin_decimal_t.
A pointer to the error buffer.
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.
void
pbo_decimal_multiply_assign(
pin_decimal_t *pdp1,
const pin_decimal_t *pdp2,
pin_errbuf_t *ebufp);
The pointer to an input pin_decimal_t.
The pointer to another input pin_decimal_t.
A pointer to the error buffer.
This function returns a pointer to a new pin_decimal_t that has the reverse sign of the input decimal. If the input decimal has a value of 0, it returns a pointer to another pin_decimal_t with the value of 0.
Table 2-2 contains examples, where x is a pointer pin_decimal_t:
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.
pin_decimal_t*
pbo_decimal_round(
const pin_decimal_t *decp,
int32 scale,
int32 rounding_mode,
pin_errbuf_t *ebufp);
A pointer to the input pin_decimal_t.
See "About Scaling".
A pointer to the error buffer.
This function replaces the value of the first argument with the value of the argument rounded according to the specified scale and rounding mode.
void
pbo_decimal_round_assign(
pin_decimal_t *decp,
int32 scale,
int32 rounding_mode,
pin_errbuf_t *ebufp);
A pointer to the input pin_decimal_t.
See "About Scaling".
A pointer to the error buffer.
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.
This function subtracts two pin_decimal_t parameters and returns a pointer to a new pin_decimal_t containing the difference.
pin_decimal_t*
pbo_decimal_subtract(
const pin_decimal_t *nump,
const pin_decimal_t *byp,
pin_errbuf_t *ebufp);
The pointer to the pin_decimal_t from which to subtract.
The pointer to the pin_decimal_t to subtract.
A pointer to the error buffer.
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.
void
pbo_decimal_subtract_assign(
pin_decimal_t *pdp1,
const pin_decimal_t *pdp2,
pin_errbuf_t *ebufp);
The pointer to an input pin_decimal_t.
The pointer to another input pin_decimal_t.
A pointer to the error buffer.
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.
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().
This section describes error-handling macros.
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.
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.
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.
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.
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.
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.
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.
A pointer to the flist to be printed in addition to the log message.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
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.
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.
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.
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.
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.
A pointer to the POID to be printed in addition to the standard log entry information.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
Sets the mask for which level of errors should be logged and which ones suppressed. All messages with a level of level or less are printed. All messages with a level greater than level are suppressed. Errors come in the levels listed in Table 2-3:
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.
Returns 0 if the macro is successful. Returns a non-zero value if an error occurred. The only possible failure is the specification of an unreasonable value for level.
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.
The path of the file to be used as the log file. The file is opened exactly as specified, so relative paths will work, but they will be relative to the current directory of the running program.
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.
The name of the running program to be printed in log messages. If the pointer is NULL, the current name is not changed.
Returns 0 if the macro is successful. Returns a non-zero value if an error occurred. The only possible failure condition is the specification of a NULL pointer.
This macro is used for a newly allocated or defined error buffer structure to initialize the contents of the error buffer to 0.
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.
A pointer to an error buffer. Used by the macro to determine whether an error has occurred.
Returns 0 if the error buffer contains no error. Returns a non-zero value if the error buffer contains an error.
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.
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.
EXTERN
void
pin_set_err(
pin_errbuf_t *ebuf,
int32 location,
int32 pin_errclass,
int32 pin_err,
int32 field,
int32 rec_ID,
int32 reserved);
A pointer to the error buffer.
The location of an error. For a list of possible locations, see "BRM Error Locations" in BRM System Administrator's Guide.
One of the four classes. See "BRM Error Classes" in BRM System Administrator's Guide.
One of the system error codes. For a list of possible error codes, see "BRM Error Codes"in BRM System Administrator's Guide.
Set to 0 or to the applicable PIN_FLD_xxx.
Set to 0 or to the record ID of the array element the error occurred on.
Set to 0 or to a value chosen to provide further information about the specific error.
This section describes flist field-handling macros.
This BRM macro gets the value of the next simple field, substructure, or element of an array in an flist. It lets an application walk an flist retrieving each field value.
The value returned is a pointer to the actual field value, and the field remains unchanged on the original flist. The value returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the value is needed, the application must either make a copy of the returned value or take it according to its type as listed in Table 2-4:
| Field Type | Macro to Use |
|---|---|
|
Simple |
PIN_FLIST_FLD_TAKE |
|
Substructure |
PIN_FLIST_SUBSTR_TAKE |
|
Array element |
PIN_FLIST_ELEM_TAKE |
#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);
A pointer to the flist containing the field being obtained.
A pointer to the field.
The element ID, in case of array field is returned if not NULL.
The cookie for the next field.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
pin_flist_t *
PIN_FLIST_ELEM_ADD(
pin_flist_t *flistp,
pin_fld_num_t fld,
v_int32 elem_id,
pin_errbuf_t *ebufp);
A pointer to the flist receiving the array element.
The number of the field being added.
The element ID of the element being added.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the flist for the array element. Returns NULL if an error occurred.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
int32
PIN_FLIST_ELEM_COPY(
pin_flist_t *src_flistp,
pin_fld_num_t src_fld,
pin_rec_id_t src_recID,
pin_flist_t *dest_flistp,
pin_fld_num_t dest_fld,
pin_rec_id_t dest_recID,
pin_errbuf_t *ebufp );
A pointer to the source flist from which the element is copied.
The element that is copied from the source flist.
The record ID of the element that is copied.
A pointer to the destination flist to which an element is copied.
The copied element in the destination flist.
The record ID of the copied element in the destination flist.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
int32
PIN_FLIST_ELEM_COUNT(
pin_flist_t *flistp,
pin_fld_num_t fld,
pin_errbuf_t *ebufp);
A pointer to the flist being counted.
The field number of the array containing the elements being counted. Each time a field with this number is found, the element count is incremented.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns the number of elements found as an unsigned integer. Returns 0 if an error occurred.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro drops the specified array element from an flist. The element flist is destroyed and the memory reallocated.
Important:
This opcode causes an array to shift its indexing if an element other than the last is dropped. Do not use this PIN_FLIST_ELEM_DROP in a loop of PIN_FLIST_ELEM_GET_NEXT calls; the off-set will cause elements to be skipped.
#include "pcm.h"
void
PIN_FLIST_ELEM_DROP(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 elem_id,
pin_errbuf_t *ebufp);
A pointer to the flist containing the array element being removed.
The field number of the array containing the element being removed.
The element ID of the element being removed.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
pin_flist_t *
PIN_FLIST_ELEM_GET(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 elem_id,
int32 optional,
pin_errbuf_t *ebufp);
A pointer to the flist containing the array element being obtained.
The field number of the array containing the element being obtained.
The ID of the array you need returned.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set, and the element is not found, an error condition is set.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
pin_flist_t *
PIN_FLIST_ELEM_GET_NEXT(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 *elem_idp,
int32 optional,
pin_cookie_t *cookie,
pin_errbuf_t *ebufp);
A pointer to the flist containing the array element being obtained.
The field number of the array containing the element being taken.
A pointer to the number of the array element being taken.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
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.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
int32
PIN_FLIST_ELEM_MOVE(
pin_flist_t *src_flistp,
pin_fld_num_t src_fld,
pin_rec_id_t src_recID,
pin_flist_t *dest_flistp,
pin_fld_num_t dest_fld,
pin_rec_id_t dest_recID,
pin_errbuf_t *ebufp );
A pointer to the source flist from which the element is moved.
The element that is moved from the source flist.
The record ID of the element that is moved.
A pointer to the destination flist to which an element is moved.
The moved element in the destination flist.
The record ID of the moved element in the destination flist.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_ELEM_PUT(
pin_flist_t *flistp,
pin_flist_t *elem_flistp,
pin_fld_num_t fld,
int32 elem_id,
pin_errbuf_t *ebufp);
A pointer to the destination flist.
A pointer to the flist containing the array element being added.
The field number of the array receiving the element.
The number of the element being put on the flist.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_ELEM_SET(
pin_flist_t *flistp,
void *elem_flistp,
pin_fld_num_t fld,
int32 elem_id,
pin_errbuf_t *ebufp);
A pointer to the destination flist for the element.
A pointer to the flist for the input element.
The field number of the array receiving the element.
The number of the element being added.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
pin_flist_t *
PIN_FLIST_ELEM_TAKE(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 elem_id,
int32 optional,
pin_errbuf_t *ebufp);
A pointer to the flist containing the element being taken.
The field number of the array whose element is being taken.
The number of the element being taken.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the element flist. Returns NULL if an error occurred or the element is not found.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
pin_flist_t *
PIN_FLIST_ELEM_TAKE_NEXT(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 *elem_idp,
int32 optional,
pin_cookie_t *cookie,
pin_errbuf_t *ebufp);
A pointer to the flist of the array containing the element being taken.
The field number of the array containing the element being taken.
A pointer to the number of the element being taken.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
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.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
int32
PIN_FLIST_FLD_COPY(
pin_flist_t *src_flistp,
pin_fld_num_t src_fld,
pin_flist_t *dest_flistp,
pin_fld_num_t dest_fld,
pin_errbuf_t *ebufp);
A pointer to the source flist from which the field is copied.
The field that is copied from the source flist.
A pointer to the destination flist to which a field is copied.
The copied field in the destination flist.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro removes a field from an flist, destroying the value of the field and reallocating the memory.
#include "pcm.h"
void
PIN_FLIST_FLD_DROP(
pin_flist_t *flistp,
pin_fld_num_t fld,
pin_errbuf_t *ebufp);
A pointer to the flist containing the substructure.
The field number of the substructure being removed.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro gets the value of a field from an flist. The value returned is a pointer to the actual value owned by the flist, and the field remains on the original flist, unchanged. The value returned must be treated as read-only to maintain the integrity of the flist. If a writable copy of the value is needed, the application must either make a copy of the returned value or use PIN_FLIST_FLD_TAKE to take ownership of the field from the flist.
Caution:
The pointer returned is valid only until you modify the flist by setting a field, retrieving a field, or destroying the flist. To ensure that you have a valid pointer, always use PIN_FLIST_FLD_GET immediately before you use the field, or dereference the pointer returned from PIN_FLIST_FLD_GET and store the value locally.Important:
To copy a field from one flist to another, use PIN_FLIST_FLD_COPY instead of PIN_FLIST_FLD_GET and PIN_FLIST_FLD_SET. To copy an element from one flist to another, use PIN_FLIST_ELEM_COPY.
#include "pcm.h"
void *
PIN_FLIST_FLD_GET(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 optional,
pin_errbuf_t *ebufp);
A pointer to the flist containing the field being obtained.
The number of the field being obtained.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
int32
PIN_FLIST_FLD_MOVE(
pin_flist_t *src_flistp,
pin_fld_num_t src_fld,
pin_flist_t *dest_flistp,
pin_fld_num_t dest_fld,
pin_errbuf_t *ebufp );
A pointer to the source flist from which a field is moved.
The field that is moved from the source flist.
A pointer to the destination flist into which a field is moved.
The moved field in the destination flist.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro puts a field (including its data value) in an flist. The memory holding the value must be dynamically allocated. The dynamic memory holding the value is given to the flist as part of the put. This is useful for adding a field to the flist without copying its value, if that memory is no longer needed by the application.
Important:
To move fields between flists or to rename fields, use PIN_FLIST_FLD_MOVE, PIN_FLIST_ELEM_MOVE, and PIN_FLIST_FLD_RENAME instead of PIN_FLIST_FLD_TAKE and PIN_FLIST_FLD_PUT.After the value of the field has been added to an flist using this macro, the caller can no longer access the value directly using the pointer to the value. The flist management system may optimize memory usage by moving where the value is stored, so the original pointer is no longer valid.
If the specified field already exists in the flist, the previous value is destroyed and replaced by the new value.
If an error condition exists or this macro otherwise fails, the field being put is destroyed. The memory is deallocated and an error is returned to the error buffer.
#include "pcm.h"
void
PIN_FLIST_FLD_PUT(
pin_flist_t *flistp,
pin_fld_num_t fld,
void *valp,
pin_errbuf_t *ebufp);
A pointer to the flist receiving the field.
The number of the field being added.
A pointer to the field value being added.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_FLD_RENAME(
pin_flist_t *flistp,
pin_fld_num_t src_fld,
pin_fld_num_t dest_fld,
pin_errbuf_t *ebufp)
A pointer to the flist in which a field is renamed.
The field that is renamed.
The new name of the field.
A pointer to an error buffer. Used to pass status information back to the caller.
If the field is not found, the error buffer contains a PIN_ERR_NOT_FOUND error.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro adds a field and a value to an flist. A dynamic copy of the specified value is made for the flist. The value passed does not have to be in dynamic memory. The value passed is unaffected by the macro.
If the specified field already exists in the flist, the existing value is destroyed and replaced by the new value.
Important:
To copy a field from one flist to another, use PIN_FLIST_FLD_COPY instead of PIN_FLIST_FLD_GET and PIN_FLIST_FLD_SET. To copy an element from one flist to another, use PIN_FLIST_ELEM_COPY.
#include "pcm.h"
void
PIN_FLIST_FLD_SET(
pin_flist_t *flistp,
pin_fld_num_t fld,
void *valp,
pin_errbuf_t *ebufp);
A pointer to the flist receiving the field.
The number of the field being added.
A pointer to the field value.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro takes a field from an flist and returns its value. The dynamically allocated memory holding the field value is returned to the application. The application is then responsible for freeing this memory when it is no longer needed. This macro is useful when fields will not be needed after the field value is retrieved.
Caution:
If you use PIN_FLIST_FLD_GET, you should do so before using this macro. PIN_FLD_FLIST_TAKE can modify the memory locations of the flist, making the PIN_FLIST_FLD_GET pointer invalid. To ensure that the pointer to the flist remains valid, always call PIN_FLIST_FLD_GET immediately before using the field.Use PIN_FLIST_FLD_GET when a read-only pointer to the field is needed.
Important:
To move fields between flists or to rename fields, use PIN_FLIST_FLD_MOVE, PIN_FLIST_ELEM_MOVE, and PIN_FLIST_FLD_RENAME instead of PIN_FLIST_FLD_TAKE and PIN_FLIST_FLD_PUT.
#include "pcm.h"
void *
PIN_FLIST_FLD_TAKE(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 optional,
pin_errbuf_t *ebufp);
A pointer to the flist containing the field being taken.
The number of the field being taken.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
pin_flist_t *
PIN_FLIST_SUBSTR_ADD(
pin_flist_t *flistp,
pin_fld_num_t fld,
pin_errbuf_t *ebufp);
A pointer to the flist receiving the substructure.
The field number of the substructure being added.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the flist for the substructure. Returns NULL if an error occurred.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro removes a substructure from an flist, freeing the allocated memory.
#include "pcm.h"
void
PIN_FLIST_SUBSTR_DROP(
pin_flist_t *flistp,
pin_fld_num_t fld,
pin_errbuf_t *ebufp);
A pointer to the flist containing the substructure being dropped.
The field number of the substructure being dropped.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void *
PIN_FLIST_SUBSTR_GET(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 optional,
pin_errbuf_t *ebufp);
A pointer to the flist with the substructure being obtained.
The field number of the substructure being obtained.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the substructure flist. Returns NULL if an error occurred or if the element is not found.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_SUBSTR_PUT(
pin_flist_t *flistp,
void *substr_flistp,
pin_fld_num_t fld,
pin_errbuf_t *ebufp);
A pointer to the flist being added.
A pointer to the flist containing the substructure being added.
The field number of the substructure being added.
A pointer to the error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_SUBSTR_SET(
pin_flist_t *flistp,
void *substr_flistp,
pin_fld_num_t fld,
pin_errbuf_t *ebufp);
A pointer to the flist receiving the substructure.
A pointer to the flist containing the substructure being added.
The field number of the substructure being added.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void *
PIN_FLIST_SUBSTR_TAKE(
pin_flist_t *flistp,
pin_fld_num_t fld,
int32 optional,
pin_errbuf_t *ebufp);
A pointer to the flist containing the substructure being taken.
The field number of the substructure being removed from flistp.
If this flag is set (by passing in a non-0 value) and the element is not found, no error condition is set. If this flag is not set and the element is not found, an error condition is set.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This section describes flist management macros.
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.
#include "pcm.h"
void
PIN_FLIST_CONCAT(
pin_flist_t *dest_flistp,
pin_flist_t *src_flistp,
pin_errbuf_t *ebufp);
A pointer to the destination flist.
A pointer to the source flist.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
A pointer to the flist to be copied.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
A pointer to an flist to count the fields of.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
Returns a pointer to the flist, in the form of pin_flist_t*. Returns NULL if an error occurred.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
A pointer to the flist to destroy.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.A pointer to the flist to destroy.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
A pointer to the flist to print.
A pointer to a file to print a message to. If the value of this pointer is NULL, the message is printed to stdout.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_SORT(
pin_flist_t *flistp,
pin_flist_t *sort_listp,
int32 sort_default,
pin_errbuf_t *ebufp);
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.
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.
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
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_SORT_REVERSE(
pin_flist_t *flistp,
pin_flist_t *sort_listp,
int32 sort_default,
pin_errbuf_t *ebufp);
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.
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.
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
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_STR_TO_FLIST(
char *str,
int64 default_db,
pin_flist_t **flistp,
pin_errbuf_t *ebufp);
A pointer to a string containing an flist in ASCII form.
A specified database number. If the ASCII string contains the sub-string "$DB", the database number in this parameter will replace it.
A pointer to a buffer for the return flist.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro prints, in ASCII format, the contents of an flist to a buffer.
#include "pcm.h"
void
PIN_FLIST_TO_STR(
pin_flist_t *flistp,
char **strpp,
int32 *lenp,
pin_errbuf_t *ebufp);
A pointer to the flist to print to a string.
A pointer to a buffer for the return string. If the value is NULL, a buffer is allocated using malloc.
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.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro prints, in compact binary form, the contents of an flist to a buffer.
#include "pcm.h"
void
PIN_FLIST_TO_STR_COMPACT_BINARY(
pin_flist_t *flistp,
char **strpp,
int32 *lenp,
pin_errbuf_t *ebufp);
A pointer to the flist to print to a string.
A pointer to a buffer for the return string. If the value is NULL, a buffer is allocated using malloc.
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.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_FLIST_TO_XML(
pin_flist_t *flistp,
int32 flags,
int32 encoding,
char **bufpp,
int *lenp,
char *root_elemname,
pin_errbuf_t *ebufp);
A pointer to the flist to convert.
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.
Specify UTF8.
A pointer to the buffer that will contain the XML converted data.
The size of the buffer that bufpp points to.
The root element name. If you do not specify this field, the default root element name, document, is used.
A pointer to an error buffer. Used to pass status information back to the caller.
This macro uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This section describes POID management macros.
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.
#include "pcm.h"
int32
PIN_POID_COMPARE(
poid_t *poidp1,
poid_t *poidp2,
int32 check_rev,
pin_errbuf_t *ebufp);
A pointer to the first POID to be compared.
A pointer to the second POID to be compared.
Determines whether or not the revision level of two POIDs is compared. If check_rev is set to 0, only the POID ID, database number, and type are compared. If check_rev is set to a non-zero value, the POID ID, database number, type, and revision number are compared.
A pointer to an error buffer. Used to pass status information back to the caller.
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.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
A pointer to the source POID.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro creates a POID. The POID uses dynamically allocated memory, and ownership of the POID is given to the caller. A copy is made of type, so it does not need to be in dynamic memory when passed.
id is typically initialized as 0. The create operation finds the next available ID in the database and uses it when creating the object.
A source POID with a type of NULL is handled correctly. See the "Portal Object ID (POID)" in BRM Developer's Guide for more information on POIDs.
#include "pcm.h"
poid_t*
PIN_POID_CREATE(
int64 db,
char *type,
int64 id,
pin_errbuf_t *ebufp);
The database number.
The data type for the new POID. See the list of objects in "Storable Class Definitions". Examples are /service and /event/customer/nameinfo.
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.
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
A pointer to the POID to be destroyed.
A pointer to an error buffer. Used to pass status information back to the caller. This parameter is optional. If a NULL is passed in, no error information is returned.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.A pointer to the destination string.
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).
A pointer to an error buffer. Used to pass status information back to the caller.
Returns a pointer to the POID created from the input string if the macro is successful. Returns NULL if the macro fails.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro returns the POID's revision level. The revision level is incremented each time any portion of the object is updated.
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.
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.
This macro adds a POID to the POID list.
#include "pcm.h"
void
PIN_POID_LIST_ADD_POID(
char **strpp,
poid_t *pdp,
int32 flag,
pin_errbuf_t *ebufp)
Pointer to the POID list.
Pointer to the POID to be added to the list.
A PCM flag (PCM_FLDFLG_FIFO or PCM_FLDFLG_CMPREV).
Pointer to the error buffer.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro copies a POID list.
#include "pcm.h"
poid_list_t *
PIN_POID_LIST_COPY(
poid_list_t *src_pldp,
pin_errbuf_t *ebufp)
Returns a pointer to the newly created POID list if the macro is successful. Returns NULL if the macro fails.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro copies 'next' POID from the POID list.
#include "pcm.h"
poid_t *
pin_poid_list_get_next(
char *strp,
int32 optional,
pin_cookie_t *cookiep,
pin_errbuf_t *ebufp)
Pointer to the POID list from which the next POID is to be copied.
If this flag is set to a non-zero value and the element is not found, no error condition is set. If this flag is not set, and the element is not found, an error condition is set.
The cookie for the next POID.
Pointer to the error buffer.
Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro copies the specified POID from the POID list.
#include "pcm.h"
poid_t*
PIN_POID_LIST_COPY_POID(
char *strp,
void *vp,
int32 flags,
pin_errbuf_t *ebufp)
Pointer to the POID list.
Pointer to the POID to be copied.
A PCM flag (PCM_FLDFLG_CMPREV or PCM_FLDFLG_TYPE_ONLY) to check for the existence of the POID to be copied.
Pointer to the error buffer.
Returns a pointer to the newly created POID if the macro is successful. Returns NULL if the macro fails.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro creates a POID list.
Returns a pointer to the newly created POID list if macro is successful. Returns NULL if the macro fails.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro frees a POID list.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro removes a POID from the POID list.
#include "pcm.h"
void
PIN_POID_LIST_REMOVE_POID(
char **strpp,
poid_t *pdp,
int32 check_rev,
pin_errbuf_t *ebufp)
Pointer to the POID list.
Pointer to the POID to be removed from the list.
Determines the existence of the POID to be removed. If check_rev is set to 0, existence of the POID is checked.
Pointer to the error buffer.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro takes the 'next' POID from the POID list.
#include "pcm.h"
poid_t *
pin_poid_list_take_next(
char **strpp,
int32 optional,
pin_errbuf_t *ebufp)
Pointer to the POID list.
If this flag is set to a non-zero value and the element is not found, no error condition is set. If this flag is not set, and the element is not found, an error condition is set.
Pointer to the error buffer.
Returns a pointer to the POID taken from the POID list if the macro is successful. Returns NULL if the macro fails.
This macro uses series-style ebuf error handling. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This macro prints a POID.
A pointer to the POID to print.
The FILE pointer to the file to receive the message. If the value of FILE is NULL, the message is printed to stdout.
A pointer to an error buffer. Used to pass status information back to the caller.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
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.
#include "pcm.h"
void
PIN_POID_TO_STR(
poid_t *poidp,
char **strpp,
int32 *lenp,
pin_errbuf_t *ebufp);
A pointer to the POID to be printed.
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.
The length of the buffer.
A pointer to an error buffer. Used to pass status information back to the caller.
This routine uses series-style ebuf error handling. Applications can call any number of series ebuf–style API routines using the same error buffer, and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors. See "Understanding API Error Handling and Logging" in BRM Developer's Guide for details on error handling algorithms.
This section describes 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.
UNIX, Windows, and Java use different locale IDs. So BRM includes a locale table, which maps the BRM locale to locale strings for various platforms.
Similar to UNIX, the BRM locale is either:
The two-character ISO code for the language. These two-character locales are used for a language in its country of origin. For example, fr designates French used in France.
A concatenation of the two-character ISO code for the language and the two-character ISO code for the country. For example, en_US designates English in the United States.
The locale description IDs are mapped to a /strings table containing the textual description of the supported locales. This table and the BRM table name are stored in the database under /config/locales.
For more information on BRM locale names, see "Locale Names" in BRM Developer's Guide.
Storable Class Hierarchy for Localized Strings
BRM includes a /strings storable class to store localized strings.
Note:
You cannot extend the /strings storable class.Structure of the /strings storable class:
/strings
POID PIN_FLD_POID
TIMESTAMP PIN_FLD_CREATED_T
TIMESTAMP PIN_FLD_MOD_T
STRING PIN_FLD_DOMAIN required, length = 1023
STRING PIN_FLD_DESCR optional, length = 1023
STRING PIN_FLD_LOCALE required, length = 1023
INT PIN_FLD_STRING_ID required
INT PIN_FLD_STR_VERSION required
STRING PIN_FLD_STRING required, length = 1023
STRING PIN_FLD_HELP_STRING optional, length = 1023
For descriptions of the fields, see the /strings storable class description.
Important:
Do not change these names and numbers or the information will not be accessible.For detailed information on BRM locale mapping, see "Locale Names" in BRM Developer's Guide.
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
You can create message strings in multiple languages to obtain all the reason codes for English.
This is an example definition:
string_list_t*
pcm_get_localized_string_list(
pcm_context_t *context_p,
const char *locale_p,
const char *domain_p,
const int32 string_id,
const int32 string_vers,
pin_errbuf_t *ebufp);
The top-level function, pcm_get_localized_string_list, allows arbitrary queries on the /strings table. The argument list is similar to pcm_get_localized_string except that message buffers are not supplied by the caller. The function can accept a null locale string, a null domain string, a string ID = -1, or a string version = -1 to indicate that the argument is not part of the search.
This example shows retrieving strings:
pcm_get_localized_string_list(context_p,"en_US","Reason Codes-Active Status Reasons",-1,1,ebufp);
is equivalent to:
select*
from strings_t
where locale = "en_US" AND
domain = "Reason Codes-Active Status Reasons" AND
string_vers = 1
which returns a set of string objects for any locale ID fitting these criteria. The function returns a container object of type string_list_t.
Table 2-5 lists String Manipulation Functions.
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.
This function deallocates the object and its flist when finished with the string list.
Important:
To prevent memory leaks, you must call this after calling pcm_get_string_list.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.
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 are used to get and set relative offset values for validity periods that start and end after a relative period passes. For example, a product's cycle fee period can become effective three months after the product is purchased.
Relative validity period information is stored in the BRM database in DETAILS fields. There are DETAILS fields for product, discount, and resource-balance validity periods. The specific name of the fields vary, but all end with "_DETAILS".
Relative validity period information includes the following values:
Mode - Specifies generally when the validity period starts or ends and can be one of these:
PIN_VALIDITY_ABSOLUTE = 0
PIN_VALIDITY_IMMEDIATE = 1
PIN_VALIDITY_NEVER = 2
PIN_VALIDITY_FIRST_USAGE = 3
PIN_VALIDITY_RELATIVE = 4
Unit - Specifies the type of offset unit, which can be one of these:
Seconds = 1
Minutes = 2
Hours = 3
Days = 4
Months = 5
Event cycles = 7
Accounting cycles = 8
Billing cycles = 9
None = 0
Offset - Specifies the number of units in the offset period.
Note:
Not all of the unit and mode values listed above can be used with every relative validity period in BRM. The unit and mode you can specify depends on the validity period you're setting and whether you're setting the start or end time. For more information, see the following topics:For information about the relative start and end times of products and discounts in price plans, see "Managing /deal Objects" in BRM Setting Up Pricing and Rating.
For information about the relative start and end times of products and discounts owned by accounts, see "Managing Purchase, Cycle, and Usage Validity Periods of Products and Discounts" in BRM Managing Customers.
For information about the relative start and end times of resource balances, see "Managing the Validity Period of Granted Resources" in BRM Setting Up Pricing and Rating.
This macro retrieves the relative offset unit from the start- or end-time details value that is passed in.
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.
This macro retrieves the mode value from the start- or end-time details value that is passed in.
This macro sets the relative offset unit in the start- or end-time details value that is passed in.
The encoded value of the start- or end-time details field.
The offset unit value to set.
This macro sets the relative offset (number of offset units) in the start- or end-time details value that is passed in.
#include "pcm.h"
u_int32
PIN_VALIDITY_SET_OFFSET(
u_int32 encoded_value,
u_int32 offset_value);
The encoded value of the start- or end-time details field.
The offset value to set.
This macro sets the relative mode in the start- or end-time details value passed in.
#include "pcm.h"
u_int32
PIN_VALIDITY_SET_MODE(
u_int32 encoded_value,
pin_validity_modes_t mode_value);
The encoded value of the start- or end-time details field.
The mode value to set.
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.
#include "pcm.h"
void
PIN_VALIDITY_DECODE_FIELD(
u_int32 encoded_value,
pin_validity_modes_t mode_variable,
u_int32 unit_variable,
u_int32 offset_variable);
The encoded value of the start- or end-time details field.
The mode variable to set.
The unit variable to set.
The offset variable to set.