The National character set (NCS) utility routines provide a
common facility for defining and accessing collating sequences
and conversion functions. Collating sequences are used to compare
strings for sorting purposes. Conversion functions are used to
derive an altered form of an input string based on an appropriate
conversion algorithm.
1 – NCS$COMPARE
The NCS$COMPARE routine compares two strings using a specified
collating sequence as a comparison basis.
Format
NCS$COMPARE cs_id ,string_1 ,string_2
1.1 – Returns
OpenVMS usage:integer
type: longword integer (signed)
access: write only
mechanism: by value
Longword condition value. Most routines return a condition value
in R0, but the NCS$COMPARE routine uses R0 to return the result
of the comparison, as shown in the following table:
Returned
Value Comparison Result
-1 string_1 is less than string_2
0 string_1 is equal to string_2
1 string_1 is greater than string_2
The NCS$COMPARE routine uses the Signaling Mechanism to indicate
completion status as described under Condition Value Signaled.
1.2 – Arguments
cs_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: read only
mechanism: by reference
Address of a longword that NCS uses to identify a collating
sequence. The cs_id argument is required and can be obtained
by a call to the NCS$GET_CS routine.
All calls to the NCS$COMPARE routine and the call to the NCS$END_
CS routine that terminates the comparison must pass this longword
identifier. Upon completion, the NCS$END_CS routine releases the
memory used to store the collating sequence and sets the value of
the longword identifier to 0.
string_1
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Descriptor (length and address) of the first string.
string_2
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Descriptor of the second string.
1.3 – Description
The NCS$COMPARE routine compares two strings using the specified
collating sequence as the comparison basis. The routine indicates
whether the value of the first string is greater than, less than,
or equal to the value of the second string.
1.4 – Condition Value Signaled
STR$_ILLSTRCLA Illegal string class. Severe error. The
descriptor of string_1 or string_2, or both,
contains a class code not supported by the
OpenVMS Calling Standard.
2 – NCS$CONVERT
The NCS$CONVERT routine converts a string using the specified
conversion function.
Format
NCS$CONVERT cf_id ,source ,dest [,ret_length] [,not_cvt]
2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
2.2 – Arguments
cf_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: read only
mechanism: by reference
Address of a longword that NCS uses to identify a conversion
function. The cf_id argument is required and can be obtained by a
call to the NCS$GET_CF routine.
All calls to the NCS$CONVERT routine and the call to the NCS$END_
CF routine that terminates the conversion must pass this longword
identifier. Upon completion, the NCS$END_CF routine releases the
memory used to store the conversion function and sets the value
of the longword identifier to 0.
source
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Descriptor of source string.
dest
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Descriptor of destination string.
ret_length
OpenVMS usage:word unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of converted string.
not_cvt
OpenVMS usage:word unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters in the source string that were not fully
converted.
2.3 – Description
Using the specified conversion function, the NCS$CONVERT routine
converts the source string and stores the result in the specified
destination. Optionally, the calling program can request that the
routine return the length of the converted string as well as the
number of characters that were not fully converted.
2.4 – Condition Values Returned
SS$_NORMAL Normal successful completion.
NCS$_NOT_CF Name of identifier does not refer to a
conversion function.
STR$_TRU Successful completion. However, the resultant
string was truncated because the storage
allocation for the destination string was
inadequate.
2.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.
Any value signaled by STR$COPY_DX or STR$ANALYZE_SDESC.
3 – NCS$END_CF
The NCS$END_CF routine terminates a conversion function.
Format
NCS$END_CF cf_id
3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
3.2 – Argument
cf_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: modify
mechanism: by reference
Address of a longword that NCS uses to store a nonzero value
identifying a conversion function.
The cf_id argument is required.
3.3 – Description
The NCS$END_CF routine indicates to NCS that the calling program
no longer needs the conversion function. NCS releases the memory
space allocated for the coversion function and sets the value of
the longword identifier to 0.
3.4 – Condition Values Returned
NCS$_NORMAL Normal successful completion. The longword
identifier value is set to 0.
NCS$_NOT_CF Name of identifier does not refer to a
conversion function.
4 – NCS$END_CS
The NCS$END_CS routine terminates a collating sequence.
Format
NCS$END_CS cs_id
4.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
4.2 – Argument
cs_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: modify
mechanism: by reference
Address of a longword that NCS uses to store a nonzero value
identifying a collating sequence.
The cs_id argument is required.
4.3 – Description
The NCS$END_CS routine indicates to NCS that the calling program
no longer needs the collating sequence. NCS releases the memory
space allocated for the collating sequence and sets the value of
the longword identifier to 0.
4.4 – Condition Values Returned
NCS$_NORMAL Normal successful completion. The longword
identifier value is set to 0.
NCS$_NOT_CS Name of identifier does not refer to a
collating sequence.
5 – NCS$GET_CF
The NCS$GET_CF routine retrieves the definition of the named
conversion function from the NCS library.
Format
NCS$GET_CF cf_id [,cfname] [,librar]
5.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
5.2 – Arguments
cf_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: modify
mechanism: by reference
Address of a longword used by NCS to identify a conversion
function. The calling program must ensure that the longword
contains 0 before invoking the NCS$GET_CF routine because the
routine stores a nonzero value in the longword. The nonzero value
identifies the conversion function. All subsequent calls to the
NCS$CONVERT routine and the call to the NCS$END_CF routine to
terminate the conversion function pass the longword identifier.
When it completes the conversion, the NCS$END_CF routine releases
the memory used to store the conversion function and sets the
value of the longword identifier to 0.
The conversion function identifier enhances modular programming
and permits concurrent use of multiple conversion functions
within a program.
The calling program should not attempt to interpret the contents
of the longword identifier.
The cf_id argument is required.
cfname
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the conversion function being retrieved.
librar
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the library where the conversion function is stored.
5.3 – Description
The NCS$GET_CF routine extracts the named conversion function
from the specified NCS library.
If the calling program omits the cfname argument, an "identity"
conversion function padded with NUL characters (hex 0) is
provided. The identity conversion function effectively leaves
each character unchanged by converting each character to itself.
For example, A becomes A, B becomes B, C becomes C, and so forth.
If the calling program omits the librar argument, NCS accesses
the default NCS library.
5.4 – Condition Values Returned
NCS$_DIAG Operation completed with signaled diagnostics.
NCS$_NOT_CF Name of identifier does not refer to a
conversion function.
NCS$_NOT_FOUND Name of identifier not found in the NCS
library.
5.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.
6 – NCS$GET_CS
The NCS$GET_CS routine retrieves the definition of the named
collating sequence from the NCS library.
Format
NCS$GET_CS cs_id [,csname] [,librar]
6.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
6.2 – Arguments
cs_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: modify
mechanism: by reference
Address of a longword that NCS uses to store a nonzero value
identifying a collating sequence. The calling program must ensure
that the longword identifier contains 0 before invoking the
NCS$GET_CS routine.
All subsequent calls to the NCS$COMPARE routine and the call to
the NCS$END_CS routine that terminates the use of the collating
sequence must pass this longword identifier. Upon completion
of the comparisons, the NCS$END_CS routine releases the memory
used to store the collating sequence and sets the value of the
longword identifier to 0.
The collating sequence identifier enhances modular programming
and permits concurrent use of multiple collating sequences within
a program.
The calling program should not attempt to interpret the contents
of the longword identifier.
The cs_id argument is required.
csname
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the collating sequence being retrieved.
librar
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification of the library where the collating sequence is
stored.
6.3 – Description
The NCS$GET_CS routine extracts the named collating sequence
from the specified NCS library. If the calling program omits the
csname argument, NCS creates a collating sequence that uses the
"native" collating sequence as a basis for the comparisons. This
collating sequence is padded with NUL characters (hex 0).
If the calling program omits the librar argument, NCS accesses
the default NCS library.
6.4 – Condition Values Returned
NCS$_DIAG Operation completed with signaled diagnostics.
NCS$_NOT_CS Name of identifier does not refer to a
collating sequence.
NCS$_NOT_FOUND Name of identifier not found in the NCS
library.
6.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.
7 – NCS$RESTORE_CF
The NCS$RESTORE_CF routine permits the calling program to restore
the definition of a saved conversion function from a database or
a file.
Format
NCS$RESTORE_CF cf_id [,length] [,address]
7.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. The condition value that this routine
can return is listed under Condition Value Returned.
7.2 – Arguments
cf_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: write only
mechanism: by reference
Address of a longword that NCS uses to identify a conversion
function.
The cf_id argument is required.
length
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword that the calling program uses to indicate the length of
the conversion function being restored.
address
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword that the calling program uses as a pointer to the
conversion function being restored.
7.3 – Description
The NCS$RESTORE_CF routine, used in conjunction with the
NCS$SAVE_CF routine, permits the application program to keep a
local copy of the conversion function. The NCS$SAVE_CF routine
obtains the length and location of the conversion function and
returns it to the application program. The application program
subsequently provides this information to the NCS$RESTORE_CF
routine, which uses it to access the conversion function.
This routine also does some integrity checking on the conversion
function as it is being processed.
7.4 – Condition Value Returned
NCS$_NOT_CF Name of identifier does not refer to a
conversion function.
7.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.
8 – NCS$RESTORE_CS
The NCS$RESTORE_CS routine permits the calling program to restore
the definition of a "saved" collating sequence from a database or
a file.
Format
NCS$RESTORE_CS cs_id [,length] [,address]
8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. The condition value that this routine
can return is listed under Condition Value Returned.
8.2 – Arguments
cs_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: write only
mechanism: by reference
Address of a longword that NCS uses to identify a collating
sequence.
The cs_id argument is required.
length
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword that the calling program uses to indicate the length of
the collating sequence being restored.
address
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword that the calling program uses as a pointer to the
collating sequence being restored.
8.3 – Description
The NCS$RESTORE_CS routine, used in conjunction with the
NCS$SAVE_CS routine, permits the application program to keep a
local copy of the collating sequence. The NCS$SAVE_CS routine
obtains the length and location of the collating sequence and
returns it to the application program. The application program
subsequently provides this information to the NCS$RESTORE_CS
routine, which uses it to access the collating sequence.
This routine also does some integrity checking on the collating
sequence as it is being processed.
8.4 – Condition Value Returned
NCS$_NOT_CS Name of identifier does not refer to a
collating sequence.
8.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.
9 – NCS$SAVE_CF
The NCS$SAVE_CF routine provides the calling program with
information that permits the application to store the definition
of a conversion function in a local database or a file rather
than in the NCS library.
Format
NCS$SAVE_CF cf_id [,length] [,address]
9.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. The condition value that this routine
can return is listed under Condition Value Returned.
9.2 – Arguments
cf_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: read only
mechanism: by reference
Address of a longword that NCS uses to identify a conversion
function.
The cf_id argument is required.
length
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Longword used to store the length of the specified conversion
function.
address
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Longword used to store the address of the specified conversion
function.
9.3 – Description
The NCS$SAVE_CF routine, used in conjunction with the
NCS$RESTORE_CF routine, permits the application program to
store a conversion function definition in a local file or in
a database. When the calling program specifies the conversion
function identifier, NCS returns the location of the definition
and its length in bytes, permitting the calling program to
store the definition locally, rather than in an NCS library.
Subsequently, the application supplies this information to the
NCS$RESTORE_CF routine, which restores the conversion function to
a form that can be used by the NCS$CONVERT routine.
This routine also does some integrity checking on the conversion
function as it is being processed.
9.4 – Condition Value Returned
NCS$_NOT_CF Name of identifier does not refer to a
conversion function.
9.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.
10 – NCS$SAVE_CS
The NCS$SAVE_CS routine provides the calling program with
information that permits the application program to store the
definition of a collating sequence in a database or a file rather
than in the NCS library.
Format
NCS$SAVE_CS cs_id [,length] [,address]
10.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. The condition value that this routine
can return is listed under Condition Value Returned.
10.2 – Arguments
cs_id
OpenVMS usage:identifier
type: longword integer (unsigned)
access: read only
mechanism: by reference
Address of a longword that NCS uses to identify a collating
sequence.
The cs_id argument is required.
length
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Longword that NCS uses to indicate the length of the specified
collating sequence to the calling program.
address
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Longword that NCS uses to indicate the address of the specified
collating sequence to the calling program.
10.3 – Description
The NCS$SAVE_CS routine, used in conjunction with the
NCS$RESTORE_CS routine, permits the application program to store
a collating sequence definition in a local file or in a database.
When the calling program specifies the collating sequence
identifier, NCS returns the location of the definition sequence
and its length in bytes, permitting the calling program to store
the definition locally, rather than in a library. Subsequently,
the application supplies this information to the NCS$RESTORE_CS
routine, which restores the collating sequence to a form that can
be used by the NCS$COMPARE routine.
This routine also does some integrity checking on the collating
sequence as it is being processed.
10.4 – Condition Value Returned
NCS$_NOT_CS Name of identifier does not refer to a
collating sequence.
10.5 – Condition Values Signaled
LBR messages (prefaced by an NCS message) might signal errors
detected while the process is accessing the NCS library.