HP 3000 Manuals HP 3000 Manuals
Operation
This section describes how to prepare and run your program using the NLS
facility.
If full screen ACCEPT operations are to be used, you must set the range
of data keys to be accepted in the ADISCTRL
database. See Chapter 20 , ADIS for details. The Micro Focus COBOL
system relies on UNIX to provide the appropriate national language tables
for the language, country and character set selected by the user.
To use the NLS facility you must have a terminal which can support
eight-bit character sets, and which must be configured to operate in
eight-bit mode.
Compiling Programs with NLS
To use the NLS facility in your program, you must set the NLS compiler
directive,
which by default is not set. For details on how to set this directive,
see Chapter 3 , Compiling.
In a suite of programs, you can compile some with NLS and some without.
However, before compiling a program with the NLS directive set, you must
ensure that it does not contain any of the following syntax:
In the Object-Computer paragraph, the phrase:
* PROGRAM COLLATING SEQUENCE IS alphabet-name
In the Special-Names paragraph, the phrases:
* alphabet-name IS
* STANDARD-1
* NATIONAL
* literal-1 THRU literal-2
* CURRENCY SIGN IS literal
* DECIMAL-POINT IS COMMA
In the Procedure Division, the phrase:
* COLLATING SEQUENCE IS alphabet-name
in MERGE or SORT statements.
If you attempt to compile a program which contains any of the above
syntax, with the NLS compiler directive set, compilation will fail with
the error:
136 Illegal use of phrase for NLS operation
See the section "Mixing Programs With and Without NLS" later in this
chapter for details.
Setting up the National Language Environment
Before you run a program with the NLS facility, you must set up the LANG
environment variable:
LANG=language-name
export LANG
where:
language-name is the language environment in which you wish to run
your program. See your operating system
documentation for details.
Running Your NLS Program
You run programs with the NLS facility in the same way as you run
programs without it. See Chapter 7 , Running for full details on how
to run programs.
The RTS initializes
the NLS facility only once during an application's run; when it
encounters the first program within the suite which was compiled with the
NLS directive set. It uses the LANG environment variable
to determine which language environment to set up for this program. The
RTS uses the same language environment for any subsequent programs within
the suite which are compiled for NLS. See the section "Mixing Programs
With and Without NLS" later in this chapter for details. If an error
occurs during this initialization process, for example the language
specified in the LANG environment variable is not supported, the RTS
reports the error:
40 Language Initialization not set up correctly
and terminates its run.
You must also note that you cannot use indexed files created with one
collating sequence in a file language environment that uses a different
collating sequence. If you attempt to do so, and you have specified file
status bytes in your program, the COBOL system may be able to detect
this, in which case the file status 9/45 is returned. If you have not
specified file status bytes in your program the RTS returns the error:
45 Attempt to open an NLS file using incompatible language
definition
When you run a program which has been compiled with the NLS directive
set, the following operations
are carried out in accordance with the rules of the language specified in
the LANG environment variable:
* string comparisons
* class condition tests
* key comparisons in indexed sequential files
* comparisons performed as part of a SORT or MERGE statement
See the following sections for further details on these features.
Other language-dependent features, such as the symbols used to denote the
decimal points and the currency character, also appear in the format of
the specified language. However, in languages that define the currency
sign as trailing, this has no effect and the usual COBOL rules are
observed.
Certain NLS definitions have characters other than the ASCII characters
0-9 defined as numerics.
Although such characters are identified as numeric by the operating
system routine isdigit, they cannot be accepted into numeric picture
strings, nor can they be used in numeric operations. Note that in all
NLS operations in the COBOL environment, a numeric item must be formed
only from the ASCII digits 0-9, with or without the ASCII operational
signs "+" or "-". There is no means of automatically converting the NLS
representation to the ASCII equivalent.
It is possible to enter European modifying characters into numeric ACCEPT
fields. These are accepted as zero.
Note that the values assigned to figurative constants, for example
LOW-VALUES, are not changed by using NLS features.
You can also use the ADIS Flip Case Control
key when using NLS characters. However, if you attempt to convert a
European character that has no equivalent defined in the NLS tables, then
the character is left unreplaced.
String Comparisons.
For programs which have been compiled with the NLS directive set, the RTS
invokes the
nl_strcoll,
nl_strxfrm or
nl_cobcmp routines when it needs to carry out string comparisons. Full
details on the use of these routines can be found in Volume 3 - X/Open
Portability Guide (XPG), with the exception of the nl_cobcmp routine
which is described later in this chapter.
During a MOVE operation of one alphanumeric item to another which is
longer, padding with spaces occurs. Similar padding is also implied
before the comparison of two such items. In both cases, an ASCII space
is assumed.
Class Condition Tests.
For programs which have been compiled with the NLS directive set, the RTS
invokes the functions
isalpha,
isupper,
islower and
isdigit when it needs to carry out class condition tests. These tests
determine if a string of information is in ALPHABETIC, ALPHABETIC-UPPER,
ALPHABETIC-LOWER, NUMERIC or user-defined CLASS condition format. The
numeric test always tests that all characters are in the range of ASCII
0-9.
Full details on the use of these routines can be found in Volume 3 -
X/Open Portability Guide (XPG).
Indexed Sequential File Operations.
If the logical file-name of an indexed sequential file, (either before or
after it has been resolved by use of environment variables as described
in Chapter 12 , COBOL File Handling) is preceded by the five
characters
"%NLS%", the file is treated as an NLS file. This is provided that the
program which OPENs that file has been compiled with the NLS directive
set. The RTS invokes the
nl_strcoll or the
nl_strxfrm routine for all key comparisons associated with NLS files.
Full details on the use of these routines can be found in Volume 3 -
X/Open Portability Guide (XPG).
If the logical file-name, (after it has been resolved using environment
variables) is preceded by "%NLS%", but the program which OPENs the file
has been compiled without the NLS directive set, the OPEN will fail and
the RTS will return the error:
44 Attempt to OPEN an NLS file in a Non-NLS Program
When the RTS opens an NLS file, it checks that the program that opens the
file has been compiled with the NLS directive set. If it is, the file is
opened correctly. If it is not, the OPEN fails and the RTS returns the
error:
45 Attempt to OPEN an NLS file using incompatible language
definition
Note that if your file contains variable length records, the NLS
collating sequence is not used.
Comparisons During SORT or MERGE Operations.
If a file to be used in SORT or MERGE operations is to use NLS key
comparisons, the logical file-name of the work file must be preceded by
the characters "%NLS%"
in the ASSIGN statement, and the program which OPENs it must be compiled
with the NLS directive set. This is as described in the previous section
for indexed sequential files. As for indexed sequential files, the RTS
invokes the
nl_strcoll or the
nl_strxfrm routine for all key comparisons associated with NLS files used
in SORT or MERGE operations.
User Interfaces.
If you require information concerning the language environment you are
using, for example nl_langinfo, you can access the NLS routines supported
by your Micro Focus COBOL system. Full details on these routines can be
found in Volume 3 - X/Open Portability Guide (XPG).
Routines which you may find particularly useful are:
cobgetenv
nl_cobcmp
These routines are described in the following sections.
cobgetenv
This routine returns the value of the environment variables LANG and
NLSPATH. It has the form:
CALL "cobgetenv" USING env-name
where:
env-name is a PIC X(n) data item and is either the LANG or
NLSPATH environment variable. For details on these,
see Appendix I , Environment Variables.
nl_cobcmp
This routine provides additional string comparison facilities. Volume 3
- X/Open Portability Guide (XPG) describes the string comparison routines
nl_strcoll and nl_strxfrm, which act on NULL (LOW-VALUES) terminated
strings and strings of equal length respectively. These are insufficient
for a full COBOL implementation of the IF statement. The nl_cobcmp
routine has been defined to be consistent with both the X/OPEN routines
and with the COBOL language. Where this routine is not directly
supported by the version of UNIX installed on your machine, details of
how this is implemented are given in your Release Notes.
The nl_cobcomp routine has the form:
CALL "nl_cobcmp" USING s1, s2, BY VALUE n1, n2
where:
s1 and s2 are PIC X(n) data items containing strings of
characters to be compared
n1 and n2 are PIC 9(9) comp-5 data items giving the respective
physical lengths of the strings to be compared.
The strings may include one or more NULL (LOW-VALUE) characters.
nl_cobcmp compares the two strings and returns an integer less than,
equal to, or greater than zero, according to whether s1 is less than,
equal to, or greater than s2 according to the language dependent
"dictionary" ordering of data. That is, it takes into account case and
accent priority, "1-to-1", "1-to-2", "2-to-1" and "don't care" character
mappings as appropriate for each specific UNIX environment.
As described in your Language Reference, if operands are of unequal size,
comparison proceeds as though the shorter operand were extended on the
right by sufficient spaces to make the operands of equal size.
In this context, spaces have the same representation as used for padding
operands of unequal length in the MOVE statement, and are ASCII spaces
unless the Release Notes specify an alternative representation.
In an NLS environment, the logical length after any "1-to-2" or "2-to-1"
mapping is used. For example, the two data items below are of unequal
physical length, but the logical length of the values are both equal to
two; hence, under NLS only, no padding of a space character is required.
Working-Storage Section.
01 item-1 pic x value "AE".
01 item-2 pic xx value "AE".
Mixing Programs With and Without NLS
If you have a suite of programs, you can compile individual COBOL
programs with the NLS directive set. A program which was compiled
without the NLS directive set facility can call programs which were
compiled without this directive set and programs which were compiled with
it set. Equally, a program compiled with the NLS directive set can call
programs compiled with this directive and those compiled without it.
When you enter a program with the NLS facility from a program without it,
or vice versa, the language environment
automatically changes. If you have programs with the NLS facility within
a program suite, you must ensure that these programs all use the same
language. This is because the RTS initializes the NLS facility only once
during an applications run - when it encounters the first program within
the suite which was compiled for NLS. Once this program has been loaded
successfully, subsequent programs within the suite compiled for NLS use
the language environment created for it. You cannot change the language
environment after this even if you change the setting of the LANG
environment variable.
See the section "Running Your NLS Program" for further details on
initializing the NLS facility.
You can pass parameters from a program with the NLS facility to a program
without it. However, you must note that parameters which are dependent
on the language environment in which they are created, will retain their
format regardless of the language environment in which they are used. If
you attempt to use a parameter created in a program with the NLS
facility, in a program without the NLS facility, the result may not be as
you would expect. We recommend that you do not attempt to pass such
parameters to programs other than those which have the same language
environment.