 |
CEELCNV,
which calls the C function localeconv(),
queries the numeric formatting information from the current locale
and sets the components of a structure with values pertaining to the
LC_NUMERIC and LC_MONETARY categories. It sets the components of an
object of the type NM_STRUCT with the values appropriate for the formatting
of the numeric quantities (monetary and otherwise) according to the
rules of the current locale.
CEELCNV is sensitive to the locales
set by setlocale() or CEESETL, not to the Language Environment settings
from COUNTRY or CEE3CTY. 
Syntax
>>-CEELCNV--(--version--,--num_and_mon--,--fc--)---------------><
- version
- This parameter points to a user supplied VERSION_INFO structure,
in which the first four bytes contain the callable service version
number.
Requirement: If the parameter does not point to
a user supplied VERSION_INFO structure, it must be omitted.
If
the parameter points to a VERSION_INFO containing version number 2,
CEELCNV returns a num_and_mon structure with the international monetary
string formatting elements added for ISO/IEC 9899:1999 (C99). This
corresponds to the current C language lconv structure.
If the parameter is omitted, CEELCNV returns the structure format
used before C99. For information about how to code this parameter,
see Invoking callable services.
- num_and_mon (output)
- Points to the numeric and monetary structure that is filled in
by this service. If the service fails, the contents of the structure
are undefined. num_and_mon has the following
structure:
- NM_STRUCT
- A halfword length-prefixed character string (VSTRING). A pointer
to the filled-in structure NM_STRUCT is returned. The structure pointed
to by the return value should not be modified by the program but can
be overridden by subsequent calls to CEELCNV. In addition, calls to
CEESETL with the LC_ALL, LC_MONETARY or LC_NUMERIC categories can
cause subsequent calls to CEELCNV to return different values based
on the selection of the locale.
The members of the structure with
the type VSTRING are strings, any of which (except decimal_point)
can point to an empty string, to indicate that the value is not available
in the current locale or is of zero length. The members with type
VINT are non-negative numbers, any of which can be CHAR_MAX to indicate
that the value is not available in the current locale. The members
include the following: - VSTRING decimal_point
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the decimal-point character used to format non-monetary quantities.
- VSTRING thousands_sep
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the character used to separate groups of digits to the left
of the decimal point in formatted non-monetary quantities.
- VSTRING grouping
- A halfword length-prefixed character string (VSTRING) of 22 bytes
whose elements indicate the size of each group of digits in formatted
non-monetary quantities.
- VSTRING int_curr_symbol
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the international currency symbol applicable to the current
locale, left justified within a four-character space-padded field.
- VSTRING currency_symbol
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the local currency symbol applicable to the current locale.
- VSTRING mon_decimal_point
- A halfword length-prefixed character string(VSTRING) of 22 bytes
that is the decimal point character used to format monetary quantities.
- VSTRING mon_thousands_sep
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the separator for groups of digits to the left of the decimal
point in formatted monetary quantities.
- VSTRING mon_grouping
- A halfword length-prefixed character string (VSTRING) of 22 bytes
whose elements indicate the size of each group of digits in formatted
monetary quantities.
- VSTRING positive_sign
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that indicates a non-negative-formatted monetary quantity.
- VSTRING negative_sign
- A halfword length-prefixed character string (VSTRING) of 22 bytes
used to indicate a negative-formatted monetary quantity.
- VINT int_frac_digits
- A 1-byte integer that is the number of fractional digits (those
to the right of the decimal point) to be displayed in an internationally-formatted
monetary quantity.
- VINT frac_digits
- A 1-byte integer that is the number of fractional digits (those
to the right of the decimal point) to be displayed in a formatted
monetary quantity.
- VINT p_cs_precedes
- A 1-byte integer that is set to 1 if the currency_symbol precedes
the value for a non-negative-formatted monetary quantity. It is set
to 0 if it follows.
- VINT p_sep_by_space
- A 1-byte integer that is set to 1 if the currency_symbol is
separated by a space from the value for a non-negative-formatted monetary
quantity. It is set to 0 if it is not separated.
- VINT n_cs_precedes
- A 1-byte integer that is set to 1 if the currency_symbol precedes
the value for a negative-formatted monetary quantity. It is set to
0 if it follows.
- VINT n_sep_by_space
- A 1-byte integer that is set to 1 if the currency_symbol is
separated by a space from the value for a negative-formatted monetary
quantity. It is set to 0 is it is not separated.
- VINT p_sign_posn
- A 1-byte integer that is set to a value indicating the positioning
of the positive_sign for non-negative-formatted
monetary quantity.
- VINT n_sign_posn
- A 1-byte integer that is set to a value indicating the position
of the negative_sign for negative-formatted
monetary quantity.
- VSTRING left_parenthesis
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the used to denote a negative monetary quantity.
- VSTRING right_parenthesis
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the used to denote a negative monetary quantity.
- VSTRING debit_sign
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the debit sign character in monetary formats.
- VSTRING credit_sign
- A halfword length-prefixed character string (VSTRING) of 22 bytes
that is the credit sign character in monetary formats.
- VINT int_p_cs_precedes
- A 1-byte integer that is set to 1 if the currency_symbol precedes
the value for a non-negative-formatted international monetary quantity.
It is set to 0 if it follows.
- VINT int_p_sep_by_space
- A 1-byte integer that is set to 1 if the currency_symbol is
separated by a space from the value for a non-negative-formatted international
monetary quantity. It is set to 0 if it is not separated.
- VINT int_n_cs_precedes
- A 1-byte integer that is set to 1 if the currency_symbol precedes
the value for a negative-formatted international monetary quantity.
It is set to 0 if it follows.
- VINT int_n_sep_by_space
- A 1-byte integer that is set to 1 if the currency_symbol is
separated by a space from the value for a negative-formatted international
monetary quantity. It is set to 0 is it is not separated.
- VINT int_p_sign_posn
- A 1-byte integer that is set to a value indicating the positioning
of the positive_sign for non-negative-formatted
international monetary quantity.
- VINT n_sign_posn
- A 1-byte integer that is set to a value indicating the position
of the negative_sign for negative-formatted
international monetary quantity.
- 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. |
| CEE3VN |
3 |
4087 |
Input Error: The version_info control
block contains a version number that is not valid. |
Usage notes - PL/I MTF
consideration—CEELCNV 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.
- CEELCNV does not return all numeric conventions.
- CHAR_MAX determines when no further grouping is to be performed.
The elements of grouping and mon_grouping are
interpreted according to the following CHAR_MAX settings:
- 0 specifies that the previous element is to be repeatedly used
for the remainder of the digits. Indicates that no further grouping
is to be performed.
- Any other value represents the number of digits comprising the
current group. The next element is examined to determine the size
of the next group of digits to the left of the current group.
- The value of p_sign_posn and n_sign_posn is
interpreted according to the following:
- 0
- Parentheses surround the quantity and currency_symbol.
- 1
- The sign string precedes the quantity and currency_symbol.
- 2
- The sign string follows the quantity and currency_symbol.
- 3
- The sign string immediately precedes the currency_symbol.
- 4
- The sign string immediately follows the currency_symbol.
Examples - Following is an example of CEELCNV called by COBOL.
CBL LIB,QUOTE
*Module/File Name: IGZTLCNV
*************************************************
** Example for callable service CEELCNV **
** Function: Retrieve numeric and monetary **
** format for default locale and **
** print an item. **
** Set locale to France, retrieve **
** structure, and print an item. **
** Valid only for COBOL for MVS & VM Release 2 **
** or later. **
*************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINLCNV.
DATA DIVISION.
WORKING-STORAGE SECTION.
*************************************************
** Use Locale NM-Struct for CEELCNV calls **
*************************************************
COPY CEEIGZN2M.
*
PROCEDURE DIVISION.
*************************************************
** Subroutine needed for addressing **
*************************************************
CALL "COBLCNV" USING NM-Struct.
STOP RUN.
*
IDENTIFICATION DIVISION.
PROGRAM-ID. COBLCNV.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 PTR1 Pointer.
01 Locale-Name.
02 LN-Length PIC S9(54) 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.
LINKAGE SECTION.
*************************************************
** Use Locale NM-Struct for CEELCNV calls **
*************************************************
COPY CEEIGZN2M.
*
PROCEDURE DIVISION USING NM-Struct.
*************************************************
** Call CEELCNV to retrieve values for locale**
*************************************************
CALL "CEELCNV" USING OMITTED,
ADDRESS OF NM-Struct, FC.
*************************************************
** Check feedback code and display result **
*************************************************
IF Severity = 0 THEN
DISPLAY "Default decimal point is "
DECIMAL-PT-String(1:DECIMAL-PT-Length)
ELSE
DISPLAY "Call to CEELCNV failed. " Msg-No
END-IF.
*************************************************
** Set up locale for France **
*************************************************
MOVE 54 TO LN-Length.
MOVE "Fr_FR" TO LN-String (1:LN-Length).
*************************************************
** Call CEESETL to set monetary locale **
*************************************************
CALL "CEESETL" USING Locale-Name,
LC-MONETARY, FC.
*************************************************
** Call CEESETL to set numeric locale **
*************************************************
CALL "CEESETL" USING Locale-Name,
LC-NUMERIC, FC.
*************************************************
** Check feedback code and call CEELCNV again **
** using version 2 to get at C99 mapping. **
*************************************************
IF Severity = 0
MOVE 2 TO Version
set PTR1 to address of Version-Info
CALL "CEELCNV" USING PTR1,
ADDRESS OF NM-Struct, FC
IF Severity > 0
DISPLAY "Call to CEELCNV failed. "
Msg-No
ELSE
DISPLAY "French decimal point is "
DECIMAL-PT-String(1:DECIMAL-PT-Length)
END-IF
ELSE
DISPLAY "Call to CEESETL failed. " Msg-No
END-IF.
EXIT PROGRAM.
END PROGRAM COBLCNV.
*
END PROGRAM MAINLCNV.
- Following is an example of CEELCNV called by PL/I.
*PROCESS MACRO;
/*Module/File Name: IBMLCNV */
/****************************************************/
/* Example for callable service CEELCNV */
/* Function: Retrieve numeric and monetary format */
/* structure for default locale and print an item. */
/* Set locale to France, retrieve structure and */
/* print an item. */
/****************************************************/
PLILCNV: PROC OPTIONS(MAIN);
%INCLUDE CEEIBMAW; /* ENTRY defs, macro defs */
%INCLUDE CEEIBMCT; /* FBCHECK macro, FB constants */
%INCLUDE CEEIBMLC; /* Locale category constants */
%INCLUDE CEEIBMN2M; /* NM_STRUCT for CEELCNV calls */
/* use explicit pointer for local NM_STRUCT struct */
DCL NUM_AND_MON POINTER INIT(ADDR(NM_STRUCT));
/* Point to local version_info struct and initialize*/
/* VERSION TO 2 TO USE C99 MAPPING OF NM_STRUCT */
DCL VERSN POINTER INIT(ADDR(version_info));
VERSION_INFO.VERSION = 2;
/* CEESETL service call arguments */
DCL LOCALE_NAME CHAR(256) VARYING;
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);
/* retrieve structure for default locale */
CALL CEELCNV ( *, NUM_AND_MON, FC );
PUT SKIP LIST('Default DECIMAL_POINT is ',
NM_STRUCT.DECIMAL_POINT);
/* set locale for France */
LOCALE_NAME = 'Fr_FRFRAN';
/* use LC_NUMERIC category const from CEEIBMLC */
CALL CEESETL ( LOCALE_NAME, LC_NUMERIC, FC );
/* use LC_MONETARY category const from CEEIBMLC */
CALL CEESETL ( LOCALE_NAME, LC_MONETARY, FC );
/* FBCHECK macro used (defined in CEEIBMCT) */
IF FBCHECK( FC, CEE000 ) THEN
DO;
/* retrieve active NM_STRUCT, France Locale */
CALL CEELCNV ( *VERSN, NUM_AND_MON, FC );
PUT SKIP LIST('French DECIMAL_POINT is ',
NM_STRUCT.DECIMAL_POINT);
END;
END PLILCNV;
|
z/OS Language Environment Programming Reference
Copyright IBM Corporation 1990, 2014