Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Utility Routines Manual


Previous Contents Index


Chapter 14
National Character Set (NCS) Utility Routines

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.

Table 14-1 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.

14.1.2 Sample Application Process

In a typical application, the program does the following:

  1. Prepares a string for comparison.
  2. Makes a call to the NCS$GET routine, specifying the appropriate collating sequence.
  3. Makes one or more calls to the NCS$COMPARE routine, which does the actual comparison.
  4. Terminates the comparison with a call to the NCS$END routine.

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.

Note

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; 
} 

14.3 NCS Routines

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.


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


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.


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.

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.

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.

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]


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.


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.

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.

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.

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.

NCS$END_CF

The NCS$END_CF routine terminates a conversion function.

Format

NCS$END_CF cf_id


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.


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.


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.

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.

NCS$END_CS

The NCS$END_CS routine terminates a collating sequence.

Format

NCS$END_CS cs_id


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.


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.


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.

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4493PRO_040.HTML