HP OpenVMS Utility Routines Manual
Previous Contents Index

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

The Boolean item code MAIL$_USER_SET_NO_SUB_DIRECTORY disables the use of a MAIL subdirectory for the specified user.

Specify the value 0 in the buffer length and buffer address fields of the item descriptor.

MAIL$_USER_USERNAME

MAIL$_USER_USERNAME specifies the record to be modified in the user profile database and points to the user name string. The buffer address field of the item descriptor points to a buffer that contains a character string 0 to 31 characters long.

Specify a value from 0 to 31 in the buffer length field of the item descriptor.

Setting bit 4 of DCL_CTLFLAGS, enables the user name string encoded in a character string 0 to 255 characters long.

Note
Once this bit is set, user name length is set to a maximum of 255 characters long. Even if this bit is cleared, the behavior remains unchanged, that is, supports user name length of 255 characters long, but there is no way to reset it to 31 characters long.

out_item_list


OpenVMS usage: itmlst_3
type: longword
access: write only
mechanism: by reference

Item list specifying the information you want the routine to return. The out_item_list argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by longword value of 0.

Output Item Codes

None.

Description

The MAIL$USER_SET_INFO routine modifies specified records in the user profile database. If you do not specify a user name, the routine modifies the user record associated with the calling process.

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.

Chapter 17
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.

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

17.1.1 List of NCS Routines

Table 17-1 lists the individual NCS routines.

Table 17-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.

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

17.2 Using the NCS Utility Routines: Examples

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

Example 17-1 illustrates the use of NCS utility routines in a HP Fortran for OpenVMS program.

Example 17-1 Using NCS Routines in a HP 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 17-2 illustrates the use of NCS routines in a HP C for OpenVMS VAX program.

Note
Each programming language provides an appropriate mechanism for defining symbols, status codes, completion codes, and other relevant information.

Example 17-2 Using NCS Routines in a HP 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; 
}

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

Previous Next Contents Index