|
Document revision date: 30 March 2001
|
![[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 RTL Library (LIB$) Manual
LIB$SCANC
The Scan for Characters and Return Relative Position routine is used to
find a specified set of characters in the source string. LIB$SCANC
makes the VAX SCANC instruction available as a callable routine.
Note
On Alpha systems, OpenVMS Alpha instructions perform the equivalent
operation.
|
Format
LIB$SCANC source-string ,table-array ,byte-integer-mask
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Relative position in the source string of the character that terminated
the operation, or zero if the terminator character is not found. If the
source string has a zero length, then a zero is returned.
Arguments
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Source string used by LIB$SCANC to index into a table. The
source-string argument contains the address of a
descriptor pointing to this source string.
table-array
| OpenVMS usage: |
vector_mask_byte |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference, array reference |
Table that LIB$SCANC indexes into and performs a logical AND operation
with the byte-integer-mask byte. The
table-array argument contains the address of an
unsigned byte array that is this table.
byte-integer-mask
| OpenVMS usage: |
mask_byte |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Mask on which a logical AND operation is performed with bytes in
table-array. The byte-integer-mask
argument contains the address of an unsigned byte that is this mask.
Description
LIB$SCANC uses successive bytes of the string specified by
source-string to index into a table. The byte selected
from the table is the byte on which a logical AND operation is
performed with the mask byte. The operation is terminated when the
result of the AND operation is equal to 1.
Condition Values Returned
None.
LIB$SCOPY_DXDX
The Copy Source String Passed by Descriptor to Destination routine
copies a source string passed by descriptor to a destination string.
Format
LIB$SCOPY_DXDX source-string ,destination-string
Corresponding JSB Entry Point
LIB$SCOPY_DXDX6
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Source string to be copied to the destination string by LIB$SCOPY_DXDX.
The source-string argument contains the address of a
descriptor pointing to this source string. The descriptor class can be
unspecified, fixed-length, decimal string, array, noncontiguous array,
varying, or dynamic.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string to which the source string is copied. The
destination-string argument contains the address of a
descriptor pointing to this destination string.
The following actions occur depending on the class of the destination
string's descriptor:
| Descriptor Class |
Action |
|
S, Z, SD, A, NCA
|
Copy the source string. If needed, space-fill or truncate on the right.
|
|
D
|
If the area specified by the destination descriptor is large enough to
contain the source string, copy the source string and set the new
length in the destination descriptor. If the area specified is not
large enough, return the previous space allocation (if any) and then
dynamically allocate the amount of space needed. Copy the source string
and set the new length and address in the destination descriptor.
|
|
VS
|
Copy source string to destination string up to the limit of the
descriptor MAXSTRLEN field with no padding. Readjust the current length
(CURLEN) field to the actual number of bytes copied.
|
Description
LIB$SCOPY_DXDX returns all condition values as a status; truncation is
a qualified success condition value (bit 0 set to 1).
In addition, an equivalent JSB entry point is available, with R0
containing the first argument and R1 containing the second.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. All characters in the input string were
copied to the destination string.
|
|
LIB$_STRTRU
|
Routine successfully completed. String truncated. The destination
string could not contain all of the characters copied from the source
string.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your Compaq support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
LIB$SCOPY_R_DX
The Copy Source String Passed by Reference to Destination String
routine copies a source string passed by reference to a destination
string, passed by descriptor.
Format
LIB$SCOPY_R_DX word-integer-source-length ,source-string
,destination-string
Corresponding JSB Entry Point
LIB$SCOPY_R_DX6
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
word-integer-source-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Length of the source string in bytes. The
word-integer-source-length argument is the address of an
unsigned word that contains the length of the source string.
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by reference |
Source string to be copied to the destination string by LIB$SCOPY_R_DX.
The source-string argument is the address of this
source string.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string to which the source string is copied. The
destination-string argument contains the address of a
descriptor pointing to this destination string.
Description
LIB$SCOPY_R_DX copies a source string, passed by reference, to a
destination string, passed by descriptor. It returns the status as a
condition value. Truncation is a qualified success; LIB$SCOPY_R_DX sets
bit 0 of the condition value to 1.
The actions taken by LIB$SCOPY_R_DX depend on the descriptor class of
the destination string. The following table describes these actions for
each descriptor class:
| Descriptor Class |
Action |
|
S, Z, SD, A, NCA
|
Copy the source string. If needed, space fill or truncate on the right.
|
|
D
|
If the area specified by the destination descriptor is large enough to
contain the source string, copy the source string and set the new
length in the destination descriptor.
|
|
|
If the area specified is not large enough, return the previous space
allocation, if any, and then dynamically allocate the amount of space
needed. Copy the source string and set the new length and address in
the destination descriptor.
|
|
VS
|
Copy source string to destination string up to the limit of the
decsriptor's MAXSTRLEN field with no padding. Readjust the string's
current length (CURLEN) field to the actual number of bytes copied.
|
An equivalent JSB entry is available, with R0 being the first argument,
R1 the second, and R2 the third. The length argument is passed in bits
15:0 of R0.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. All characters in the input string were
copied to the destination string.
|
|
LIB$_STRTRU
|
Routine successfully completed. String truncated. The destination
string could not contain all of the characters copied from the source
string.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your Compaq support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
LIB$SCOPY_R_DX_64 (Alpha Only)
The Copy Source String Passed by Reference to Destination String
routine copies a source string passed by reference to a destination
string, passed by descriptor.
Format
LIB$SCOPY_R_DX_64 quad-integer-source-length ,source-string
,destination-string
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
quad-integer-source-length
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Length of the source string in bytes. The
quad-integer-source-length argument is the address of
an unsigned quadword that contains the length of the source string.
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by reference |
Source string to be copied to the destination string by
LIB$SCOPY_R_DX_64. The source-string argument is the
address of this source string.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string to which the source string is copied. The
destination-string argument contains the address of a
descriptor pointing to this destination string.
Description
LIB$SCOPY_R_DX_64 copies a source string, passed by reference, to a
destination string, passed by descriptor. It returns the status as a
condition value. Truncation is a qualified success; LIB$SCOPY_R_DX_64
sets bit 0 of the condition value to 1.
The actions taken by LIB$SCOPY_R_DX_64 depend on the descriptor class
of the destination string. The following table describes these actions
for each descriptor class:
| Descriptor Class |
Action |
|
S, Z, SD, A, NCA
|
Copy the source string. If needed, space fill or truncate on the right.
|
|
D
|
If the area specified by the destination descriptor is large enough to
contain the source string, copy the source string and set the new
length in the destination descriptor.
|
|
|
If the area specified is not large enough, return the previous space
allocation, if any, and then dynamically allocate the amount of space
needed. Copy the source string and set the new length and address in
the destination descriptor.
|
|
VS
|
Copy source string to destination string up to the limit of the
descriptor's MAXSTRLEN field with no padding. Readjust the string's
current length (CURLEN) field to the actual number of bytes copied.
|
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. All characters in the input string were
copied to the destination string.
|
|
LIB$_STRTRU
|
Routine successfully completed. String truncated. The destination
string could not contain all of the characters copied from the source
string.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your Compaq support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
LIB$SET_LOGICAL
The Set Logical Name routine requests the calling process's command
language interpreter (CLI) to define or redefine a supervisor-mode
process logical name. It provides the same function as the DCL command
DEFINE.
Format
LIB$SET_LOGICAL logical-name [,value-string] [,table] [,attributes]
[,item-list]
Either the item-list or value-string
argument must be specified. If both item-list and
value-string are specified, the
value-string argument is ignored.
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
logical-name
| OpenVMS usage: |
logical_name |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Logical name to be defined or redefined. The
logical-name argument contains the address of a
descriptor pointing to this logical name string. The maximum length of
a logical name is 255 characters. Note that logical names are case
sensitive.
value-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Value to be given to the logical name. The
value-string argument contains the address of a
descriptor pointing to this value string. The maximum length of a
logical name value is 255 characters.
If omitted, an item list must be present to specify the values of the
logical name.
table
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the table in which to create the logical name. The
table argument contains the address of a descriptor
pointing to the logical name table. If no table is specified,
LNM$PROCESS is used as the default.
attributes
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Logical name or translation attributes. The attributes
argument is the address of a longword bit mask that contains the
logical name or translation attributes.
LNM$M_CONFINE and LNM$M_NO_ALIAS are currently available logical name
attributes. See the description of the $CRELNM system service in the
OpenVMS System Services Reference Manual: A--GETUAI for definitions of LNM$M_CONFINE and LNM$M_NO_ALIAS. If
omitted, no special logical name attribute is established.
If no item-list is specified, the translation
attributes LNM$M_CONCEALED and LNM$M_TERMINAL may be specified. See the
description of the ASSIGN command in the OpenVMS DCL Dictionary for definitions
of these attributes. If an item-list is specified, it
will contain the translation attributes for each equivalence string in
the attribute.
item-list
| OpenVMS usage: |
item_list_3 |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference, array reference |
Item list describing the equivalence names for this logical name. The
item-list argument contains the address of an array
that contains this item list. If item-list is not
specified, the logical name will have only one value, as specified in
the value-string argument. Item codes for use with
this item list are included in libraries supplied by Compaq in module
$LNMDEF.
Either value-string or item-list must
be specified. If neither is specified, the LIB$_INVARG error is
produced. If both value-string and
item-list are specified, the
value-string argument is ignored.
If item-list is specified, only logical name
attributes are permitted. Translation attributes appear in the item
list.
The item-list argument is needed only when you want to
create multiple equivalence strings for a single logical name.
Description
If the optional table argument is defined, the logical
name will be placed in the table specified by the
table argument; otherwise, the logical name is placed
in the LNM$PROCESS table.
Unlike the system services $CRELOG and $CRELNM, LIB$SET_LOGICAL does
not require the caller to be executing in supervisor mode to define a
supervisor-mode logical name. Supervisor-mode logical names are not
deleted when an image exits. A program can obtain the current value of
any logical name by calling the system service $TRNLNM. For more
information on logical names, see the OpenVMS System Services Reference Manual.
This routine is supported for use with the DCL and MCR CLIs. If an
image is run directly as a subprocess or as a detached process, there
is no CLI present to perform this function. In that case, the error
status LIB$_NOCLI is returned.
This routine does not support the DCL DEFINE and DEASSIGN commands'
special side-effect of opening and closing a process-permanent file if
the logical name SYS$OUTPUT is specified.
See the OpenVMS DCL Dictionary for a description of the DEFINE command.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_ACCVIO
|
Access violation. The logical name or its value could not be read.
|
|
SS$_BADPARAM
|
Bad argument.
|
|
SS$_BUFFEROVF
|
Routine successfully completed; however, a buffer overflow occurred.
|
|
SS$_INSFMEM
|
Insufficient dynamic memory.
|
|
SS$_IVLOGNAM
|
Invalid logical name. The logical name or its value contained more than
255 characters.
|
|
SS$_IVLOGTAB
|
Invalid logical name table.
|
|
SS$_NOPRIV
|
No privileges for attempted operation.
|
|
SS$_SUPERSEDE
|
Routine successfully completed; the previous definition of the logical
name was replaced.
|
|
SS$_TOOMANYLNAM
|
Logical name translation exceeded allowed depth.
|
|
LIB$_INVARG
|
Neither the
value-string nor the
item-list argument was specified.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
|
LIB$_NOCLI
|
No CLI present to perform function. The calling process did not have a
CLI to perform the function or the CLI did not support the request
type. Note that an image run as a subprocess or detached process does
not have a CLI.
|
|
LIB$_UNECLIERR
|
Unexpected CLI error. The CLI returned an error status which was not
recognized. This error may be caused by use of a nonstandard CLI. If
this error occurs while using the DCL command language interpreter,
please report the problem to your Compaq support representative.
|
Example
|
!+
! Initialize value for logical name MY_LOG
!-
SYMBOL$ = 'MY_LOG'
SETVAL$ = 'OFF'
CALL LIB$SET_LOGICAL (SYMBOL$, SETVAL$)
END
|
The BASIC program above sets the logical MY_LOG to OFF. This value can
be displayed after the program is run with SHOW LOGICAL as follows:
$ SHOW LOGICAL MY_LOG
"MY_LOG" = "OFF" (LNM$PROCESS_TABLE)
|