![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
This chapter describes the National Character Set (NCS) utility
routines. The NCS utility provides 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.
14.1 Introduction to NCS Routines
Using NCS, you can formulate collating sequences and conversion functions and register them in an NCS library. The NCS routines provide a programming interface to NCS that lets you access the collating sequences and conversion functions from an NCS library for doing string comparisons.
Typically, NCS collating sequences are selective subsets of the multinational character set. They are used extensively in programming applications involving various national character sets. For example, a program might use the Spanish collating sequence to assign appropriate collating weight to characters from the Spanish national character set. Another program might use the French collating sequence to assign appropriate collating weight to characters in the French national character set.
In addition to providing program access to collating sequences and
conversion functions in an NCS library, the NCS routines provide a
means for saving definitions in a local file for subsequent use by the
comparison and conversion routines.
14.1.1 List of NCS Routines
Table 14-1 lists the individual NCS routines.
| Routine | Description |
|---|---|
| NCS$COMPARE | Compares two strings using a specified collating sequence as comparison basis. |
| NCS$CONVERT | Converts a string using the specified conversion function. |
| NCS$END_CF | Terminates the use of a conversion function by the calling program. |
| NCS$END_CS | Terminates the use of a collating sequence by the calling program. |
| NCS$GET_CF | Retrieves the definition of the named conversion function from the NCS library. |
| NCS$GET_CS | Retrieves the definition of the named collating sequence from the NCS library. |
| NCS$RESTORE_CF | Permits the calling program to restore the definition of a "saved" conversion function from a database or an OpenVMS RMS file. |
| NCS$RESTORE_CS | Permits the calling program to restore the definition of a "saved" collating sequence from a database or an RMS file. |
| NCS$SAVE_CF | Provides the calling program with information that permits the application to store the definition of a conversion function in a local database or an RMS file. |
| NCS$SAVE_CS | Provides the calling program with information that permits the application to store the definition of a collating sequence in a local database or an RMS file. |
In a typical application, the program does the following:
The program can also include the use of conversion functions in
preparation for the comparison routines.
14.2 Using the NCS Utility Routines: Examples
This section includes two examples of how to use NCS utility routines in program applications:
Example 14-1 illustrates the use of NCS utility routines in a Fortran program.
| Example 14-1 Using NCS Routines in a Fortran Program | |||
|---|---|---|---|
PROGRAM NCS_EXAMPLE
CHARACTER*80 CSSTRING,STRING1,STRING2
INTEGER*4 CSLENGTH,LENGTH1,LENGTH2,CSID,STATUS,RESULT
INTEGER*4 NCS$GET_CS,NCS$COMPARE,NCS$END_CS
CHARACTER*1 CMP(3)
CMP(1) = '<'
CMP(2) = '='
CMP(3) = '>'
C
C Read the name of the collating sequence..
C
WRITE (6,30)
READ (5,15,END=999) CSLENGTH,CSSTRING
30 FORMAT(' Collating Sequence: ')
C
C Get the collating sequence from the NCS library
C
CSID = 0
STATUS = NCS$GET_CS (CSID, CSSTRING(1:CSLENGTH))
IF ((STATUS .AND. 1) .NE. 1) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ENDIF
C
C Read two strings to be compared according to the collating sequence
C
100 WRITE (6,10)
READ (5,15,END=999) LENGTH1,STRING1
WRITE (6,20)
READ (5,15,END=999) LENGTH2,STRING2
IF (LENGTH1 .EQ. 0 .AND. LENGTH2 .EQ. 0) THEN
GOTO 200
ENDIF
10 FORMAT(' String1: ')
20 FORMAT(' String2: ')
15 FORMAT (q,a80)
C
C Compare the strings
C
result = ncs$compare (csid, string1(1:length1), string2(1:length2))
C
C Display the results of the comparison
C
WRITE (6,40) STRING1(1:LENGTH1), CMP(RESULT+2), STRING2(1:LENGTH2)
40 FORMAT(' ',A,' ',A,' ',A)
GOTO 100
C
C Come here if both inputs are blank -- we are done.
C Call NCS$END_CS to free any storage used to hold the CS.
C
200 STATUS = NCS$END_CS (CSID)
IF ((STATUS .AND. 1) .NE. 1) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ENDIF
CALL EXIT
999 CONTINUE
END
|
Example 14-2 illustrates the use of NCS routines in a VAX C program.
Each programming language provides an appropriate mechanism for defining symbols, status codes, completion codes, and other relevant information. |
| Example 14-2 Using NCS Routines in a VAX C Program | |||
|---|---|---|---|
/*
** ============================================================================
**
** NCS_EXAMPLE.C
**
** NCS conversion function example using the VAX C programming language
**
** ============================================================================
*/
/*
** ----------------------------------------------------------------------------
** Header files
*/
# include "sys$library:descrip.h" /* Descriptor macros */
# include "sys$library:rms.h" /* RMS structure definitions */
# include "sys$library:rmsdef.h" /* RMS completion codes */
# include "sys$share:ssdef.h" /* System service completion */
/* codes */
# include "sys$library:stdio.h" /* Standard I/O definitions */
/*
** ----------------------------------------------------------------------------
** Data definitions
*/
#define SIZE 1024 /* Maximum record size */
unsigned long int
cfid, /* Address of conversion */
/* function */
expected_status, /* Expected return status */
rms_status, /* RMS return status */
status; /* Function return status */
unsigned short int
return_length; /* Length of returned string in */
/* bytes */
char
file[NAM$C_MAXRSS], /* File name */
inrec[SIZE], /* Input record */
outrec[SIZE]; /* Output record */
$DESCRIPTOR(cfname_d,"EDT_VT2xx"); /* Conversion function name */
/* descriptor */
$DESCRIPTOR(prompt_d,"_File: "); /* Prompt string descriptor */
$DESCRIPTOR(file_d,file); /* File name descriptor */
$DESCRIPTOR(inrec_d,inrec); /* Input record descriptor */
$DESCRIPTOR(outrec_d,outrec); /* Output record descriptor */
struct FAB infab; /* Input file access block */
struct RAB inrab; /* Input record access block */
/*
** ----------------------------------------------------------------------------
** Function prototypes
*/
void status_check();
/*
** ============================================================================
*/
main ()
{
/*
** ------------------------------------------------------------------------
** Initialize RMS user structures for the file.
*/
infab = cc$rms_fab; /* Initialize to default FAB */
/* values */
infab.fab$l_fna = file; /* Now supply our specific */
/* values */
infab.fab$b_fns = NAM$C_MAXRSS;
inrab = cc$rms_rab; /* Initialize to default RAB */
/* values */
inrab.rab$l_fab = &infab; /* Now supply our specific */
/* values */
inrab.rab$l_ubf = inrec;
inrab.rab$w_usz = SIZE;
/*
** ------------------------------------------------------------------------
** Get the EDT_VT2xx conversion function from the default NCS library
*/
cfid = 0; /* Initialize ID */
status = ncs$get_cf(&cfid,&cfname_d,0);
status_check(status,SS$_NORMAL);
/*
** ------------------------------------------------------------------------
** Get the file to be converted and set the length of the returned file
** name
*/
status = lib$get_input(&file_d,&prompt_d,&return_length);
status_check(status,SS$_NORMAL);
file_d.dsc$w_length = return_length;
/*
** ------------------------------------------------------------------------
** Open the input file to be converted and connect to the RAB
*/
rms_status = sys$open(&infab,0,0);
status_check(rms_status,RMS$_NORMAL);
rms_status = sys$connect(&inrab,0,0);
status_check(rms_status,RMS$_NORMAL);
/*
** ------------------------------------------------------------------------
** Read each record from the file, convert the input string to EDT
** fallback, and write the result to the output
*/
while(TRUE)
{
/*
** --------------------------------------------------------------------
** Read each record
*/
rms_status = sys$get(&inrab,0,0);
if (rms_status == RMS$_EOF) /* Reached end of file */
break;
else
status_check(rms_status,RMS$_NORMAL); /* Read a record */
/*
** --------------------------------------------------------------------
** Call NCS$CONVERT to convert the input string to EDT fallback
**
** e.g. Convert form feed to <FF>, escape to <ESC>, et cetera
*/
inrec_d.dsc$w_length = inrab.rab$w_rsz;
status = ncs$convert(&cfid,&inrec_d,&outrec_d,&return_length);
status_check(status,SS$_NORMAL);
outrec_d.dsc$w_length = return_length;
/*
** --------------------------------------------------------------------
** Write the result to the output, SYS$OUTPUT in this case
*/
status = lib$put_output(&outrec_d);
status_check(status,SS$_NORMAL);
outrec_d.dsc$w_length = SIZE;
}
/*
** ------------------------------------------------------------------------
** Close the input file.
*/
rms_status = sys$close(&infab,0,0);
status_check(rms_status,RMS$_NORMAL);
/*
** ------------------------------------------------------------------------
** Free any storage used to hold the conversion function.
*/
status = ncs$end_cf(&cfid);
status_check(status,SS$_NORMAL);
}
void status_check(status,expected_status)
/*
** ============================================================================
**
** Checks the function return status against the one expected, and exits upon
** error. Otherwise, return to the main program.
**
** ============================================================================
*/
{
if (status != expected_status)
sys$exit(status);
else
return;
}
|
This section describes the NCS routines.
Note that several routines contain the heading Condition Value Signaled to indicate that the condition value originates in another utility.
The NCS$COMPARE routine compares two strings using a specified collating sequence as a comparison basis.
NCS$COMPARE cs_id ,string_1 ,string_2
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.
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.
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.
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.
The NCS$CONVERT routine converts a string using the specified conversion function.
NCS$CONVERT cf_id ,source ,dest [,ret_length] [,not_cvt]
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.
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.
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.
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.
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.
The NCS$END_CF routine terminates a conversion function.
NCS$END_CF cf_id
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.
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.
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.
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.
The NCS$END_CS routine terminates a collating sequence.
NCS$END_CS cs_id
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.
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.
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.
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.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4493PRO_040.HTML | ||