HP OpenVMS Utility Routines Manual


Previous Contents Index


NCS$END_CF

The NCS$END_CF routine terminates a conversion function.

Format

NCS$END_CF cf_id


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.


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.


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.

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.

NCS$END_CS

The NCS$END_CS routine terminates a collating sequence.

Format

NCS$END_CS cs_id


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.


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.


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.

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.

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]


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

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.


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.

Condition Values Signaled

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

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]


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

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.

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.


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.

Condition Values Signaled

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

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]


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.


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.

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.


Condition Value Returned

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

Condition Values Signaled

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

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]


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.


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.

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.


Condition Value Returned

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

Condition Values Signaled

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

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]


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.


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.


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.


Condition Value Returned

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

Condition Values Signaled

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

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]


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.


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.

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.


Condition Value Returned

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

Condition Values Signaled

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


Previous Next Contents Index