Document revision date: 30 March 2001

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

| privacy and legal statement |
4493PRO_046.HTML