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 adisctrldatabase. See the chapter
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 8-bit
character sets, and which must be configured to operate in 8-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 the chapter Compiler.
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 try 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 want 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 the chapter Running for full details on how to
run programs.
The RTS initializesthe 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
variableto 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 National Language Environment not set up correctly
and terminates its run.
You must not use indexed files with variable length records when the NLS
directive is set.
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 try 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
* comparisons of alphanumeric or group items
* 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.
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 zeros.
The values assigned to figurative constants, for example LOW-VALUES, are
not changed by using NLS features.
Unpredictable results occur in the following circumstances when you use
the NLS facility:
* An item in a conditional expression contains the value LOW-VALUE.
* An indexed file key contains the value LOW-VALUE.
* An elementary item of a group that is part of a conditional
expression is not USAGE DISPLAY.
* An elementary item of an indexed file key is not USAGE DISPLAY.
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 the chapter File Handling) is preceded by the five characters
"%NLS%", the file is treated as being keyed according to the UNIX system
collating sequence specified in the LANG environment variable. 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
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 might find particularly useful are:
cobgetenv
nl_cobcmp
These routines are described in the following sections.
cobgetenv.
This routine returns the value of the operating system 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 your UNIX system documentation.
NOTE You can access the values of the LANG and NLSPATH environment
variables using the X/Open ACCEPT FROM environment-name and ACCEPT
FROM environment-value syntax. We recommend that you use this
syntax in preference to the cobgetenv routine.
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 can 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 can call programs compiled with this
directive set and those compiled without it. 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 environmentautomatically 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 application's
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 earlier in this
chapter 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, parameters which are dependent on the language
environment in which they are created retain their format regardless of
the language environment in which they are used. If you try 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 try to pass such parameters to programs other
than those which have the same language environment.