CEEFMON—Format monetary string

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.

For more information

For more information about the setlocale() function, see COUNTRY, CEE3CTY—Set default country, and CEE3LNG—Set national language.
For more information about the CEESETL callable service, see CEESETL—Set locale operating environment.

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;