|
CEEFMON, analogous to the C function strfmon(),
converts numeric values to monetary strings according to the specifications
passed to it. These specifications work in conjunction with the format
conversions set in the current locale. The current locale's LC_MONETARY
category affects the behavior of this service, including the monetary
radix character, the thousands separator, the monetary grouping, the
currency symbols (national and international), and formats.
CEEFMON
is sensitive to the locales set by setlocale() or
CEESETL, not to the Language Environment settings
from COUNTRY or CEE3CTY.
Syntax
>>-CEEFMON--(--omitted_parm--,--stringin--,--maxsize--,--------->
>--format--,--stringout--,--result--,--fc--)-------------------><
- omitted_parm
- This parameter is reserved for future expansion and must be omitted.
For information about how to code an omitted parm, see Invoking callable services.
- stringin (input)
- An 8-byte field that contains the value of a double-precision
floating point number.
- maxsize (input)
- A 4-byte integer that specifies the maximum number of bytes (including
the string terminator) that can be placed in stringout.
- format (input)
- A halfword length-prefixed character string (VSTRING) of 256 bytes
that contains plain characters and a conversion specification. Plain
characters are copied to the output stream. Conversion specification
results in the fetching of the input stringin argument
that is converted and formatted.
A conversion specification consists
of a percent character (%), optional flags, optional field width,
optional left precision, optional right precision, and a required
conversion character that determines the conversion to be performed.
- Flags (optional)
- You can specify one or more of the following flags to control
the conversion.
- =f
- An = followed by a single character f specifies
that the character f should be used as the
numeric fill character. The default numeric fill character is the
space character. This option does not affect the other fill operations
(such as field-width filling), which always use the space as the fill
character.
- ^
- Do not format the currency amount with the grouping characters.
The default is to insert the grouping characters if defined for the
current locale.
- + or (
- Specifies the style of representing positive and negative currency
amounts. You must specify either + or (.
If + is specified, the locale's equivalent
of + and - are used (for example, in USA: the empty (null) string
if positive and - (minus sign) if negative). If ( is
specified, the locale's equivalent of enclosing negative amounts within
a parenthesis is used. If this option is not included, a default specified
by the current locale is used.
- !
- Suppresses the currency symbol from the output conversion.
- Field Width (optional)
- A decimal digit string w that specifies
a minimum field width in which the result of the conversion is right-justified
(or left-justified if -w is specified).
- Left Precision (optional)
- A # (pound sign) followed by the decimal digit string n,
( specified as #n), indicates a maximum
number of digits expected to be formatted to the left of the radix
character. This option can be used to keep the formatted output from
multiple calls to the CEEFMON service aligned in the same columns.
It can also be used to fill unused positions with a special character
as in $***123.45. This option causes an amount to be formatted as
if it has the number of digits specified by n.
If more digit positions are required than are specified, this conversion
specification is ignored. Digit positions in excess of those actually
required are filled with the numeric fill character. See the =f specification
above.
If grouping is enabled, it is applied to the combined fill
characters plus regular digits. However, if the fill character is
not 0 (digit zero), grouping separators inserted after a fill character
are replaced by the same fill character ($0,001,234.56 versus $****1,234.56).
- Right Precision (optional)
- A period (.) followed by the decimal digit string p,
(specified as .p), indicates the number
of digits after the radix character. If the value of the precision p is
zero, no radix character appears. If this option is not included,
a default specified by the current locale is used. The amount being
formatted is rounded to the specified number of digits prior to formatting.
- Conversion Characters (required)
- One of the following conversion characters must be specified.
- i
- The double argument is formatted according to the locale's international
currency format (for example, in USA: USD 1,234.56).
- n
- The double argument is formatted according to the locale's national
currency format (for example, in USA: $1,234.56).
- %
- No argument is converted; the conversion specification %% is replaced
by a single %.
- stringout (output)
- Contains the output of the CEEFMON service.
- result (output)
- Contains the number of characters placed in stringout,
if successful. If unsuccessful, an error is reported.
- fc (output/optional)
- A 12-byte feedback code, optional in some languages,
that indicates the result of this service. If you choose to omit this
parameter, refer to Invoking callable services for the
appropriate syntax to indicate that the feedback code was omitted.
The
following symbolic conditions can result from this service:
Code |
Severity |
Message number |
Message text |
---|
CEE000 |
0 |
— |
The service completed successfully. |
CEE3T1 |
3 |
4001 |
General Failure: Service could not be completed. |
CEE3VM |
3 |
4086 |
Input Error: The number of characters to be formatted must
be greater than zero. |
Usage notes - PL/I MTF
consideration—CEEFMON is not supported in PL/I MTF
applications.
- This callable service uses the C/C++ runtime
library. The C/C++ library
must be installed and accessible even when this service is called
from a non-C program.
Examples - An example of CEEFMON called by COBOL:
CBL LIB,QUOTE
*Module/File Name: IGZTFMON
*************************************************
* Example for callable service CEEFMON *
* Function: Convert a numeric value to a *
* monetary string using specified *
* format passed as parameter. *
* Valid only for COBOL for MVS & VM Release 2 *
* or later. *
*************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. COBFMON.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Monetary COMP-2.
01 Max-Size PIC S9(9) BINARY.
01 Format-Mon.
02 FM-Length PIC S9(4) BINARY.
02 FM-String PIC X(256).
01 Output-Mon.
02 OM-Length PIC S9(4) BINARY.
02 OM-String PIC X(60).
01 Length-Mon PIC S9(9) BINARY.
01 Locale-Name.
02 LN-Length PIC S9(4) BINARY.
02 LN-String PIC X(256).
** Use Locale category constants
COPY CEEIGZLC.
01 FC.
02 Condition-Token-Value.
COPY CEEIGZCT.
03 Case-1-Condition-ID.
04 Severity PIC S9(4) BINARY.
04 Msg-No PIC S9(4) BINARY.
03 Case-2-Condition-ID
REDEFINES Case-1-Condition-ID.
04 Class-Code PIC S9(4) BINARY.
04 Cause-Code PIC S9(4) BINARY.
03 Case-Sev-Ctl PIC X.
03 Facility-ID PIC XXX.
02 I-S-Info PIC S9(9) BINARY.
**
PROCEDURE DIVISION.
** Set up locale name for United States
MOVE 14 TO LN-Length.
MOVE "En_US.IBM-1047"
TO LN-String (1:LN-Length).
** Set all locale categories to United States.
** Use LC-ALL category constant from CEEIGZLC.
CALL "CEESETL" USING Locale-Name, LC-ALL, FC.
** Check feedback code
IF Severity > 0
DISPLAY "Call to CEESETL failed. " Msg-No
STOP RUN
END-IF. ** Set up numeric value
MOVE 12345.62 TO Monetary.
MOVE 60 TO Max-Size.
MOVE 2 TO FM-Length.
MOVE "%i" TO FM-String (1:FM-Length).
** Call CEEFMON to convert numeric value
CALL "CEEFMON" USING OMITTED, Monetary,
Max-Size, Format-Mon
Output-Mon, Length-Mon,
FC.
** Check feedback code and display result
IF Severity > 0
DISPLAY "Call to CEEFMON failed. " Msg-No
ELSE
DISPLAY "International format is "
OM-String(1:OM-Length)
END-IF.
STOP RUN.
END PROGRAM COBFMON.
- An example of CEEFMON called by PL/I:
*PROCESS MACRO;
/*Module/File Name: IBMFMON */
/****************************************************/
/* Example for callable service CEEFMON */
/* Function: Convert a numeric value to a monetary */
/* string using specified format passed as parm */
/****************************************************/
PLIFMON: PROC OPTIONS(MAIN);
%INCLUDE CEEIBMAW; /* ENTRY defs, macro defs */
%INCLUDE CEEIBMCT; /* FBCHECK macro, FB constants */
%INCLUDE CEEIBMLC; /* Locale category constants */
/* CEESETL service call arguments */
DCL LOCALE_NAME CHAR(14) VARYING;
/* CEEFMON service call arguments */
DCL MONETARY REAL FLOAT DEC(16); /* input value */
DCL MAXSIZE_FMON BIN FIXED(31); /* output size */
DCL FORMAT_FMON CHAR(256) VARYING; /* format spec */
DCL RESULT_FMON BIN FIXED(31); /* result status */
DCL OUTPUT_FMON CHAR(60) VARYING; /* output string */
DCL 01 FC, /* Feedback token */
03 MsgSev REAL FIXED BINARY(15,0),
03 MsgNo REAL FIXED BINARY(15,0),
03 Flags,
05 Case BIT(2),
05 Severity BIT(3),
05 Control BIT(3),
03 FacID CHAR(3), /* Facility ID */
03 ISI /* Instance-Specific Information */
REAL FIXED BINARY(31,0);
/* init locale name to United States */
LOCALE_NAME = 'En_US.IBM-1047';
/* use LC_ALL category constant from CEEIBMLC */
CALL CEESETL (LOCALE_NAME, LC_ALL, FC);
/* FBCHECK macro used (defined in CEEIBMCT) */
IF FBCHECK (FC, CEE2KE) THEN
DO; /* invalid locale name */
DISPLAY ('Locale LC_ALL Call '||FC.MsgNo);
STOP;
END;MONETARY = 12345.62; /* monetary numeric value */
MAXSIZE_FMON = 60; /* max char length returned */
FORMAT_FMON = '%i'; /* international currency */
CALL CEEFMON ( *, /* optional argument */
MONETARY , /* input, 8 byte floating point */
MAXSIZE_FMON, /* maximum size of output string*/
FORMAT_FMON, /* conversion request */
OUTPUT_FMON, /* string returned by CEEFMON */
RESULT_FMON, /* no. of chars in OUTPUT_FMON */
FC ); /* feedback code structure */
IF RESULT_FMON = -1 THEN
DO;
/* FBCHECK macro used (defined in CEEIBMCT) */
IF FBCHECK( FC, CEE3VM ) THEN
DISPLAY ( 'Invalid input '||MONETARY );
ELSE
DISPLAY ('CEEFMON not completed '||FC.MsgNo );
STOP;
END;
ELSE
DO;
PUT SKIP LIST(
'International Format '||OUTPUT_FMON );
END;
END PLIFMON;
|