HELPLIB.HLB  —  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.

1  –  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

1.1  –  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.

1.2  –  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.

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

1.4  –  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]

2.1  –  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.

2.2  –  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.

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

2.4  –  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.

2.5  –  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.

3  –  NCS$END_CF

    The NCS$END_CF routine terminates a conversion function.

    Format

      NCS$END_CF  cf_id

3.1  –  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.2  –  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.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.4  –  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.

4  –  NCS$END_CS

    The NCS$END_CS routine terminates a collating sequence.

    Format

      NCS$END_CS  cs_id

4.1  –  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.

4.2  –  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.

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

4.4  –  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.

5  –  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]

5.1  –  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.

5.2  –  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.

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

5.4  –  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.

5.5  –  Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.

6  –  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]

6.1  –  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.

6.2  –  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.

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

6.4  –  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.

6.5  –  Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.

7  –  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]

7.1  –  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.

7.2  –  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.

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

7.4  –  Condition Value Returned

    NCS$_NOT_CF        Name of identifier does not refer to a
                       conversion function.

7.5  –  Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.

8  –  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]

8.1  –  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.

8.2  –  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.

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

8.4  –  Condition Value Returned

    NCS$_NOT_CS        Name of identifier does not refer to a
                       collating sequence.

8.5  –  Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.

9  –  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]

9.1  –  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.

9.2  –  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.

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

9.4  –  Condition Value Returned

    NCS$_NOT_CF        Name of identifier does not refer to a
                       conversion function.

9.5  –  Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.

10  –  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]

10.1  –  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.

10.2  –  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.

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

10.4  –  Condition Value Returned

    NCS$_NOT_CS        Name of identifier does not refer to a
                       collating sequence.

10.5  –  Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.
Close Help