Binary Coded Decimal (BCD) Helper Functions

Defines

#define rtQ825TBCDToString(numocts, data, buffer, bufsiz)   rtxQ825TBCDToString(numocts, data, buffer, bufsiz)
#define rtDecQ825TBCDString(pctxt, numocts, buffer, bufsiz)   rtxDecQ825TBCDString(pctxt, numocts, buffer, bufsiz)
#define rtEncQ825TBCDString(pctxt, str)   rtxEncQ825TBCDString(pctxt, str)
#define rtTBCDBinToChar(bcdDigit, pdigit)   rtxTBCDBinToChar(bcdDigit, pdigit)
#define rtTBCDCharToBin(digit, pbyte)   rtxTBCDCharToBin(digit, pbyte)

Functions

const char * rtBCDToString (OSUINT32 numocts, const OSOCTET *data, char *buffer, size_t bufsiz, OSBOOL isTBCD)
int rtStringToBCD (const char *str, OSOCTET *bcdStr, size_t bufsiz, OSBOOL isTBCD)
int rtStringToDynBCD (OSCTXT *pctxt, const char *str, ASN1DynOctStr *poctstr)
int rtStringToTBCD (const char *str, OSOCTET *bcdStr, size_t bufsiz)
const char * rtTBCDToString (OSUINT32 numocts, const OSOCTET *data, char *buffer, size_t bufsiz)

Detailed Description

Binary Coded Decimal (BCD) helper functions provide assistance in working with BCD numbers. Functions are provided to convert to a BCD values to and from string form.

Define Documentation

#define rtDecQ825TBCDString ( pctxt,
numocts,
buffer,
bufsiz   )     rtxDecQ825TBCDString(pctxt, numocts, buffer, bufsiz)

This function decodes a Q.825 TBCD value to a standard null-terminated string. TBCD digits are read from the decode buffer/stream and converted to their character equivalents. See 'rtQ825TBCDToString' for a description of the Q.825 TBCD format.

Parameters:
pctxt Pointer to a context structure block.
numocts The number of octets in the BCD value to be read from input stream.
buffer The destination buffer. Should not be less than bufsiz argument is.
bufsiz The size of the destination buffer (in octets). The buffer size should be at least ((numocts * 2) + 1) to hold the BCD to String conversion.
Returns:
Status of conversion: 0 = success, negative = error.
Since:
6.6
#define rtEncQ825TBCDString ( pctxt,
str   )     rtxEncQ825TBCDString(pctxt, str)

This function encodes a null-terminated string Q.825 TBCD string. TBCD digits are converted and written to the encode buffer/stream. See 'rtQ825TBCDToString' for a description of the Q.825 TBCD format.

Parameters:
pctxt Pointer to a context structure block.
str Null-terminate string to be encoded. This string may only contain valid Q.825 TBCD characters.
Returns:
Status of operation: 0 = success, negative = error.
Since:
6.6
#define rtQ825TBCDToString ( numocts,
data,
buffer,
bufsiz   )     rtxQ825TBCDToString(numocts, data, buffer, bufsiz)

This function converts a Q.825 TBCD value to a standard null-terminated string. Octet values can contain the filler digit to represent the odd number of BCD digits.

The encoding is as follows per Q.825:

This type (Telephony Binary Coded Decimal String) is used to represent digits from 0 through 9, *, #, a, b, c, two digits per octet, each digit encoded 0000 to 1001 (0 to 9), 1010 (*) 1011(#), 1100 (a), 1101 (b) or 1110 (c); 1111 (end of pulsing signal-ST); 0000 is used as a filler when there is an odd number of digits.

Parameters:
numocts The number of octets in the BCD value.
data The pointer to the BCD value.
buffer The destination buffer. Should not be less than bufsiz argument is.
bufsiz The size of the destination buffer (in octets). The buffer size should be at least ((numocts * 2) + 1) to hold the BCD to String conversion.
Returns:
Status of conversion: 0 = success, negative = error.
Since:
6.6
#define rtTBCDBinToChar ( bcdDigit,
pdigit   )     rtxTBCDBinToChar(bcdDigit, pdigit)

This function converts a TBCD binary character into its ASCII equivalent.

Parameters:
bcdDigit TBCD digit
pdigit Pointer to character to receive converted character
Returns:
0 if conversion successful, or negative error code
Since:
6.6
#define rtTBCDCharToBin ( digit,
pbyte   )     rtxTBCDCharToBin(digit, pbyte)

This function converts a TBCD character ('0'-'9',"*#abc") into its binary equivalent.

Parameters:
digit TBCD digit character ('0'-'9',"*#abc")
pbyte Pointer to byte to receive binary result.
Returns:
0 if conversion successful, or negative error code
Since:
6.6

Function Documentation

const char* rtBCDToString ( OSUINT32  numocts,
const OSOCTET *  data,
char *  buffer,
size_t  bufsiz,
OSBOOL  isTBCD 
)

This function converts a packed BCD value to a standard null-terminated string. Octet values may contain filler digits if the number of BCD digits is odd.

BCD digits can be 0(0000) to 9(1001). Filler digits can be A(1010), B(1011), C(1100), D(1101), E(1110) or F(1111)

Parameters:
numocts The number of octets in the BCD value.
data The pointer to the BCD value.
buffer The destination buffer. Should not be less than buffsiz argument is.
bufsiz The size of the destination buffer (in octets). The buffer size should be atleast ((numocts * 2) + 1) to hold the BCD to String conversion.
isTBCD Whether the input data is formatted as a TBCD string or not.
Returns:
The converted null-terminated string. NULL, if error has occurred or destination buffer is not enough.
See also:
rtTBCDToString
int rtStringToBCD ( const char *  str,
OSOCTET *  bcdStr,
size_t  bufsiz,
OSBOOL  isTBCD 
)

This function converts a standard null-terminated string into a BCD value. The source string should contain only characters '0' - '9', 'A' - 'F', or 'a' - 'f'. Otherwise, an error will occur.

Parameters:
str The source standard null-terminated string.
bcdStr The destination buffer. Should not be less than bufsiz is.
bufsiz The size of the destination buffer (in octets).
isTBCD Whether the string is a TBCD string or not.
Returns:
The number of octets in the resulting BCD value or a negative value if an error occurs.
See also:
rtStringToTBCD
int rtStringToDynBCD ( OSCTXT *  pctxt,
const char *  str,
ASN1DynOctStr *  poctstr 
)

This function converts a standard null-terminated string into a BCD value. The source string should contain only characters '0' - '9', 'A' - 'F', or 'a' - 'f'. Otherwise, an error will occur.

Parameters:
str The source standard null-terminated string.
pctxt Pointer to a context structure block.
poctstr Pointer to a dynamic octet string variable. Memory will be allocated for the data member of this structure with rtMemAlloc.
Returns:
The number of octets in the resulting BCD value or a negative value if an error occurs.
int rtStringToTBCD ( const char *  str,
OSOCTET *  bcdStr,
size_t  bufsiz 
)

This function converts a standard null-terminated string into a TBCD value. The source string should contain only characters '0' - '9', 'A' - 'F', or 'a' - 'f'. Otherwise, an error will occur. A TBCD string differs from a normal BCD string in that its bytes are flipped. The BCD string 0x12345f would be represented 0x2143f5 as a TBCD string.

Parameters:
str The source standard null-terminated string.
bcdStr The destination buffer. Should not be less than bufsiz is.
bufsiz The size of the destination buffer (in octets).
Returns:
The number of octets in the resulting BCD value or a negative value if an error occurs.
Since:
6.06
const char* rtTBCDToString ( OSUINT32  numocts,
const OSOCTET *  data,
char *  buffer,
size_t  bufsiz 
)

This function converts a packed TBCD value to a standard null-terminated string. Octet value can contain the filler digit to represent the odd number of BCD digits. A TBCD string differs from a normal BCD string in that the byte values of the octets are flipped. The BCD string 0x12345f would be represented 0x2143f5 as a TBCD string.

TBCD digits can be 0(0000) to 9(1001). Filler digits can be A(1010), B(1011), C(1100), D(1101), E(1110) or F(1111)

Parameters:
numocts The number of octets in the BCD value.
data The pointer to the BCD value.
buffer The destination buffer. Should not be less than buffsiz argument is.
bufsiz The size of the destination buffer (in octets). The buffer size should be atleast ((numocts * 2) + 1) to hold the BCD to String conversion.
Returns:
The converted null-terminated string. NULL, if error has occurred or destination buffer is not enough.
Since:
6.06