1 NCS_Routines The National character set (NCS) utility routines provide 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. 2 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 3 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. 3 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. 3 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. 3 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. 2 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] 3 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. 3 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. 3 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. 3 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. 3 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. 2 NCS$END_CF The NCS$END_CF routine terminates a conversion function. Format NCS$END_CF cf_id 3 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. 3 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. 3 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. 3 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. 2 NCS$END_CS The NCS$END_CS routine terminates a collating sequence. Format NCS$END_CS cs_id 3 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. 3 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. 3 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. 3 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. 2 NCS$GET_CF The NCS$GET_CF routine retrieves the definition of the named conversion function from the NCS library. Format NCS$GET_CF cf_id [,cfname] [,librar] 3 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. 3 Arguments cf_id OpenVMS usage:identifier type: longword integer (unsigned) access: modify mechanism: by reference Address of a longword used by NCS to identify a conversion function. The calling program must ensure that the longword contains 0 before invoking the NCS$GET_CF routine because the routine stores a nonzero value in the longword. The nonzero value identifies the conversion function. All subsequent calls to the NCS$CONVERT routine and the call to the NCS$END_CF routine to terminate the conversion function pass the longword identifier. When it completes the conversion, the NCS$END_CF routine releases the memory used to store the conversion function and sets the value of the longword identifier to 0. The conversion function identifier enhances modular programming and permits concurrent use of multiple conversion functions within a program. The calling program should not attempt to interpret the contents of the longword identifier. The cf_id argument is required. cfname OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the conversion function being retrieved. librar OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the library where the conversion function is stored. 3 Description The NCS$GET_CF routine extracts the named conversion function from the specified NCS library. If the calling program omits the cfname argument, an "identity" conversion function padded with NUL characters (hex 0) is provided. The identity conversion function effectively leaves each character unchanged by converting each character to itself. For example, A becomes A, B becomes B, C becomes C, and so forth. If the calling program omits the librar argument, NCS accesses the default NCS library. 3 Condition_Values_Returned NCS$_DIAG Operation completed with signaled diagnostics. NCS$_NOT_CF Name of identifier does not refer to a conversion function. NCS$_NOT_FOUND Name of identifier not found in the NCS library. 3 Condition_Values_Signaled LBR messages (prefaced by an NCS message) might signal errors detected while the process is accessing the NCS library. 2 NCS$GET_CS The NCS$GET_CS routine retrieves the definition of the named collating sequence from the NCS library. Format NCS$GET_CS cs_id [,csname] [,librar] 3 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. 3 Arguments 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 calling program must ensure that the longword identifier contains 0 before invoking the NCS$GET_CS routine. All subsequent calls to the NCS$COMPARE routine and the call to the NCS$END_CS routine that terminates the use of the collating sequence must pass this longword identifier. Upon completion of the comparisons, the NCS$END_CS routine releases the memory used to store the collating sequence and sets the value of the longword identifier to 0. The collating sequence identifier enhances modular programming and permits concurrent use of multiple collating sequences within a program. The calling program should not attempt to interpret the contents of the longword identifier. The cs_id argument is required. csname OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the collating sequence being retrieved. librar OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification of the library where the collating sequence is stored. 3 Description The NCS$GET_CS routine extracts the named collating sequence from the specified NCS library. If the calling program omits the csname argument, NCS creates a collating sequence that uses the "native" collating sequence as a basis for the comparisons. This collating sequence is padded with NUL characters (hex 0). If the calling program omits the librar argument, NCS accesses the default NCS library. 3 Condition_Values_Returned NCS$_DIAG Operation completed with signaled diagnostics. NCS$_NOT_CS Name of identifier does not refer to a collating sequence. NCS$_NOT_FOUND Name of identifier not found in the NCS library. 3 Condition_Values_Signaled LBR messages (prefaced by an NCS message) might signal errors detected while the process is accessing the NCS library. 2 NCS$RESTORE_CF The NCS$RESTORE_CF routine permits the calling program to restore the definition of a saved conversion function from a database or a file. Format NCS$RESTORE_CF cf_id [,length] [,address] 3 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. The condition value that this routine can return is listed under Condition Value Returned. 3 Arguments cf_id OpenVMS usage:identifier type: longword integer (unsigned) access: write only mechanism: by reference Address of a longword that NCS uses to identify a conversion function. The cf_id argument is required. length OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword that the calling program uses to indicate the length of the conversion function being restored. address OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword that the calling program uses as a pointer to the conversion function being restored. 3 Description The NCS$RESTORE_CF routine, used in conjunction with the NCS$SAVE_CF routine, permits the application program to keep a local copy of the conversion function. The NCS$SAVE_CF routine obtains the length and location of the conversion function and returns it to the application program. The application program subsequently provides this information to the NCS$RESTORE_CF routine, which uses it to access the conversion function. This routine also does some integrity checking on the conversion function as it is being processed. 3 Condition_Value_Returned NCS$_NOT_CF Name of identifier does not refer to a conversion function. 3 Condition_Values_Signaled LBR messages (prefaced by an NCS message) might signal errors detected while the process is accessing the NCS library. 2 NCS$RESTORE_CS The NCS$RESTORE_CS routine permits the calling program to restore the definition of a "saved" collating sequence from a database or a file. Format NCS$RESTORE_CS cs_id [,length] [,address] 3 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. The condition value that this routine can return is listed under Condition Value Returned. 3 Arguments cs_id OpenVMS usage:identifier type: longword integer (unsigned) access: write only mechanism: by reference Address of a longword that NCS uses to identify a collating sequence. The cs_id argument is required. length OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword that the calling program uses to indicate the length of the collating sequence being restored. address OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword that the calling program uses as a pointer to the collating sequence being restored. 3 Description The NCS$RESTORE_CS routine, used in conjunction with the NCS$SAVE_CS routine, permits the application program to keep a local copy of the collating sequence. The NCS$SAVE_CS routine obtains the length and location of the collating sequence and returns it to the application program. The application program subsequently provides this information to the NCS$RESTORE_CS routine, which uses it to access the collating sequence. This routine also does some integrity checking on the collating sequence as it is being processed. 3 Condition_Value_Returned NCS$_NOT_CS Name of identifier does not refer to a collating sequence. 3 Condition_Values_Signaled LBR messages (prefaced by an NCS message) might signal errors detected while the process is accessing the NCS library. 2 NCS$SAVE_CF The NCS$SAVE_CF routine provides the calling program with information that permits the application to store the definition of a conversion function in a local database or a file rather than in the NCS library. Format NCS$SAVE_CF cf_id [,length] [,address] 3 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. The condition value that this routine can return is listed under Condition Value Returned. 3 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. length OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Longword used to store the length of the specified conversion function. address OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Longword used to store the address of the specified conversion function. 3 Description The NCS$SAVE_CF routine, used in conjunction with the NCS$RESTORE_CF routine, permits the application program to store a conversion function definition in a local file or in a database. When the calling program specifies the conversion function identifier, NCS returns the location of the definition and its length in bytes, permitting the calling program to store the definition locally, rather than in an NCS library. Subsequently, the application supplies this information to the NCS$RESTORE_CF routine, which restores the conversion function to a form that can be used by the NCS$CONVERT routine. This routine also does some integrity checking on the conversion function as it is being processed. 3 Condition_Value_Returned NCS$_NOT_CF Name of identifier does not refer to a conversion function. 3 Condition_Values_Signaled LBR messages (prefaced by an NCS message) might signal errors detected while the process is accessing the NCS library. 2 NCS$SAVE_CS The NCS$SAVE_CS routine provides the calling program with information that permits the application program to store the definition of a collating sequence in a database or a file rather than in the NCS library. Format NCS$SAVE_CS cs_id [,length] [,address] 3 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. The condition value that this routine can return is listed under Condition Value Returned. 3 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. length OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Longword that NCS uses to indicate the length of the specified collating sequence to the calling program. address OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Longword that NCS uses to indicate the address of the specified collating sequence to the calling program. 3 Description The NCS$SAVE_CS routine, used in conjunction with the NCS$RESTORE_CS routine, permits the application program to store a collating sequence definition in a local file or in a database. When the calling program specifies the collating sequence identifier, NCS returns the location of the definition sequence and its length in bytes, permitting the calling program to store the definition locally, rather than in a library. Subsequently, the application supplies this information to the NCS$RESTORE_CS routine, which restores the collating sequence to a form that can be used by the NCS$COMPARE routine. This routine also does some integrity checking on the collating sequence as it is being processed. 3 Condition_Value_Returned NCS$_NOT_CS Name of identifier does not refer to a collating sequence. 3 Condition_Values_Signaled LBR messages (prefaced by an NCS message) might signal errors detected while the process is accessing the NCS library.