HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

To modify any user record other than that associated with the calling process, you must have SYSPRV privilege. However, if you want to add or modify only the forwarding address of another user, SYSNAM privilege is sufficient.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
MAIL$_CONITMCOD	The specified item codes perform conflicting operations.
MAIL$_ILLCHAR	Unacceptable character in personal name. Utility returns three formatted ASCII output (FAO) arguments including the illegal character, the length of the string, and the string address.
MAIL$_ILLPERNAM	Personal name formatted improperly. Returns an FAO argument containing the improperly formatted personal name.
MAIL$_ILLSUBDIR	Illegal subdirectory specification. Returns an FAO argument containing the subdirectory string.
MAIL$_INVITMCOD	The specified item code is invalid.
MAIL$_INVITMLEN	The specified item length is invalid.
MAIL$_MISREQITEM	The required item is missing.
MAIL$_NAMTOOBIG	Specified name exceeds 255-character limit.
MAIL$_NOTSUBDIR	No such subdirectory. Returns an FAO argument containing the subdirectory string.
MAIL$_NOSUCHUSR	No such user. Returns the name of the unfound user.
MAIL$_NOSYSNAM	Caller needs SYSNAM privileges.
MAIL$_NOSYSPRV	Caller needs system privileges.
SS$_ACCVIO	Access violation.

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.

16.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.

16.1.1 List of NCS Routines

Table 16-1 lists the individual NCS routines.

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.

16.2 Using the NCS Utility Routines: Examples

This section includes two examples of how to use NCS utility routines in program applications:

Example 16-1 illustrates the use of NCS utility routines in a Compaq Fortran for OpenVMS 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 16-2 illustrates the use of NCS routines in a Compaq C for OpenVMS VAX 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.

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.

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.