| Previous | Contents | Index |
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.
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.
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.
| 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.
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.
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;
}
|
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.
| Previous | Next | Contents | Index |