Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Tools : $PIC

$PIC
Returns a number in a format specified by a mask. (F)
Invocation
string = $PIC(value, mask)
 
On return, contains the masked string. Its syntax is V (variable length character) with a maximum length of 80.
Contains a string of digit placeholder characters, special characters, and message characters. It can be up to 78 characters long, but cannot contain more than 31 digit placeholders.
Elements of a Display Mask
A display mask can have the following elements, all of which are optional:
A string that is appended to the basic string and appears only if value is negative.
In the following mask: US$-NNN,NNNV.99CR%paid
Using this mask, $PIC returns values such as the following:
$PIC(1234, 'US$-NNN,NNNV.99CR%paid') returns US$ 1,234.00%paid
$PIC(-12345.6, 'US$-NNN,NNNV.99CR%paid') returns US$12,345.60CR%paid
Within a particular mask, any of the four elements can be omitted. The following sections explain how to use each element.
Basic String
In the basic string, you use digit placeholders, message characters, and the decimal point placeholder to control how a given value appears. The basic string begins with the first placeholder and ends with the last placeholder.
Digit Placeholders
Digit placeholders determine how digits in the value are positioned in the masked string. $PIC uses the following digit placeholders:
Displays leading zeros.
$PIC(12, '999') returns 012
$PIC(1234, '$999,999') returns $001,234
Displays leading zeros as asterisks (*).
$PIC(12, '***') returns *12
$PIC(1234, '$***,***') returns $**1,234
Displays leading zeros as blanks.
$PIC(12, 'ZZZ') returns 12
$PIC(1234, '$ZZZ,ZZZ') returns $ 1,234
Displays leading zeros as nulls
$PIC(12, 'NNN') returns 12
$PIC(1234, '$NNN,NNN') returns $1,234
Message Characters
A display mask can optionally contain message characters that do not serve as placeholders and are output as ordinary characters. Characters other than the digit placeholders are always treated as message characters, with the following exceptions:
The characters V and percent sign (%) have specific functions and cannot be used as message characters between placeholders (refer to the sections below for more information on their function).
The digit placeholder characters asterisk (*), Z, N, and 9 can, in the following instances, function as message characters:
They precede the first dollar sign ($) in a mask.
In the mask ‘NZ$AZZ9’, the initial ‘NZ’ is an ordinary character string, and the ‘ZZ9’ after the $ are digit placeholders.
$PIC(123, 'NZ$AZZ9') returns NZ$A123
An asterisk (*), Z, or N follows a different digit placeholder.
Note  9 is always a digit placeholder even if it appears after another digit placeholder, so an asterisk (*), Z, or N following it is treated as a message character.
In the mask ‘ABCZZNZ’, all three Zs are placeholders, and the N is treated as an ordinary character.
$PIC(123, 'ABCZZNZ') returns ABC12N3
Note  Any characters after the last digit placeholder up to either the end of the string or a percent sign are conditional, and their appearance depends on the value of the sign holder in the unconditional left string. Therefore:
$PIC(123, 'ABCZZ9Z') returns ABC123, not ABC123Z.
In the mask ‘Z99%9’, the second 9 is the last digit placeholder, and the last 9 is an ordinary character.
$PIC(123, 'Z99%9') returns 123%9
For more information on how the dollar sign ($) and the percent sign (%) characters are used in other elements in the mask, refer to the sections on the unconditional left and right strings below.
Decimal Point Placeholder
$PIC(23.45, '$NNNV.99') returns $23.45
$PIC(12, '$NNNV,99') returns $12,00
If V is placed immediately after the last digit placeholder and value is positive, no decimal digits from value appear. If value is negative, only a decimal point appears:
$PIC(12.34, '9999V.') returns 0012
$PIC(-12.34, '9999V.') returns 0012.
If value contains more digits before the decimal point than the display mask can accommodate, $PIC fails, as in:
$PIC(123.4, 'NNV.NN')
$PIC(1234, 'ZZZV.99')
$PIC(1.68, 'NV.N') returns 1.6
$PIC(1.234, 'NNV.NN') returns 1.23
Conversely, if there are more placeholders for the decimal digits than there are decimal digits in value, the remaining placeholders are replaced with zeros, no matter what the regular replacement character for that placeholder are:
$PIC(3.4, '**V.***') returns *3.400
$PIC(1.23, 'NV.NNNN') returns 1.2300
*l
Basic String Omitted
If the basic string is omitted from a mask, a value of 0 or blank outputs the mask; any other value causes $PIC to fail.
$PIC(0, 'US$-') returns US$
Unconditional Left String
Use the unconditional left string to prepend message characters to the basic string. The unconditional left string consists of all characters that precede the first placeholder, and has two parts, both of which are optional: a character string and a sign holder.
Character String
To include in the unconditional left string any characters that ordinarily serve as placeholders or have special functions, place them before the first placeholders in the mask. As well, any characters preceding the first dollar sign in a mask are treated as message characters, except for the percent sign (%) character, which cannot be used in the unconditional left string. Subsequent dollar signs ($) in a mask are treated as message characters. For example:
$PIC(1234, '9V9$9,999V.99') returns 9V9$1,234.00
$PIC(1234, 'ZZ$Z$ZZZ') returns ZZ$1$234
Sign Holder
Using the sign holder, you can display whether value is positive or negative. The first positive (+) or negative (-) sign before the first placeholder is the sign holder. Subsequent positive or negative signs are treated as message characters. The sign holder follows these rules:
$PIC(6789, '+*****') returns +*6789
$PIC(-6789, '+*****') returns -*6789
$PIC(3456, 'NZ$-*****') returns NZ$ *3456
$PIC(-3456, 'NZ$-*****') returns NZ$-*3456
Conditional Right String
Use a conditional right string to append a set of message characters to the basic string that appear only when value is negative. For example, this element can be used to append the characters CR when a credit is due. The conditional right string consists of all characters after the last digit placeholder, unless a percent sign (%) marks the start of an unconditional right string. If a percent (%) sign is present, the conditional right string consists of all characters between the last digit placeholder and the percent sign, which signals the beginning of the unconditional right string (refer to Unconditional Right String below). The conditional right string follows these rules:
If value is negative, the characters in the conditional right string are appended to the basic string. The characters CR and AUS are conditional right strings in the examples below.
$PIC(-1234, 'CDN$-ZZZZV.ZZCR') returns CDN$-1234.00CR
$PIC (-2345, '-*****AUS') returns -*2345AUS
If value is positive, the characters in the conditional right string are replaced with characters that depend on the first placeholder in the basic string:
$PIC(1234, 'CDN$-ZZZZV.ZZCR') returns CDN$ 1234.00
$PIC(2345, '-*****AUS') returns *2345***
$PIC(2345, '-NNNNNAUS') returns 2345
Unconditional Right String
Use the unconditional right string to append characters to the basic string or conditional right string that always appear regardless of whether value is positive or negative. The unconditional right string begins with a percent sign (%) character. Characters that follow a percent sign (%) character appear as message characters, including all placeholders and characters with special functions.
$PIC(567.89, 'NNNNV.NNN%VALUE') returns 567.890%VALUE
$PIC(-7890.3, 'AUS$-ZZZ,ZZZV.ZZCR%PAID') returns AUS$7,890.30CR%PAID
See Also
The $UNPIC tool, which, given a masked value produced by $PIC and the display mask that produced it, determines the original value submitted.
Example
The following rule formats an input amount so that it appears with commas, a decimal marker, and a negative sign if necessary, and then displays the formatted amount in the end message.

 
RULE EDITOR ===> SCROLL: P
DISP_DOLLAR(AMOUNT);
_ LOCAL AMOUNT2;
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ AMOUNT2 = $PIC(AMOUNT, '-$NNN,NNN,NNNV.99'); | 1
_ CALL ENDMSG(AMOUNT2); | 2
_ ---------------------------------------------------------------------------

 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved