|
Document revision date: 19 July 1999
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
OpenVMS Utility Routines Manual
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.
|