 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$DELETE_LOGICAL
The Delete Logical Name routine requests the calling process' command
language interpreter (CLI) to delete a supervisor-mode process logical
name. LIB$DELETE_LOGICAL provides the same function as the DCL command
DEASSIGN.
Format
LIB$DELETE_LOGICAL logical-name [,table-name]
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 deleted. The logical-name argument
is the address of a descriptor pointing to this logical name string.
The maximum length of a logical name is 255 characters.
table-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the table from which the logical name is to be deleted. The
table-name argument is the address of a descriptor
pointing to this name string. This is an optional argument. If the
argument is omitted, the LNM$PROCESS table is used.
Description
LIB$DELETE_LOGICAL requests the calling process's command language
interpreter (CLI) to delete a supervisor-mode process logical name. If
the optional table-name argument is defined, the
logical name is deleted from that table. Otherwise, the logical name is
deleted from the LNM$PROCESS table.
Unlike the system service $DELLOG and $DELLNM, LIB$DELETE_LOGICAL does
not require the caller to be executing in supervisor mode to delete a
supervisor-mode logical name.
This routine is supported for use with the DCL and MCR command language
interpreters.
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.
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.
See the HP OpenVMS DCL Dictionary for a description of the DCL command DEASSIGN.
Condition Values Returned
|
SS$_ACCVIO
|
Access violation. The logical name could not be read.
|
|
SS$_IVLOGNAM
|
Invalid logical name. The logical name contained illegal characters or
more than 255 characters.
|
|
SS$_IVLOGTAB
|
Invalid logical name table
|
|
SS$_NOLOGNAM
|
No logical name match. The logical name was not defined as a
supervisor-mode process logical name.
|
|
SS$_NOPRIV
|
No privilege for attempted operation.
|
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_TOOMANYLNAM
|
Logical name translation exceeded allowed depth.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
|
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 that 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 HP support representative.
|
LIB$DELETE_SYMBOL
The Delete CLI Symbol routine requests the calling process's command
language interpreter (CLI) to delete an existing CLI symbol.
Format
LIB$DELETE_SYMBOL symbol [,table-type-indicator]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
symbol
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The
symbol argument is the address of a descriptor
pointing to this symbol string. The symbol name is converted to
uppercase, and trailing blanks are removed before use.
Symbol must begin with a letter, a digit, a dollar
sign ($), a hyphen (-), or an underscore (_). The maximum length of
symbol is 255 characters.
table-type-indicator
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Indicator of the table that contains the symbol to be deleted. The
table-type-indicator argument is the address of a
signed longword integer that is this table indicator.
If table-type-indicator is omitted, the local symbol
table is used. The following are possible values for the
table-type-indicator argument:
| Symbolic Name |
Value |
Table Used |
|
LIB$K_CLI_LOCAL_SYM
|
1
|
Local symbol table
|
|
LIB$K_CLI_GLOBAL_SYM
|
2
|
Global symbol table
|
Description
LIB$DELETE_SYMBOL is supported for use with the DCL CLI. The error
status LIB$_NOCLI is returned if LIB$DELETE_SYMBOL is used with the MCR
CLI or called from an image run directly as a subprocess or as a
detached process.
LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in symbol
libraries supplied by HP (macro or module name $LIBCLIDEF) and as
global symbols.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
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 HP.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVARG
|
Invalid argument. The value of
table-type-indicator was invalid.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
|
LIB$_INVSYMNAM
|
Invalid symbol name. The symbol name contained more than 255 characters
or did not begin with a letter, a digit, a dollar sign, a hyphen, or an
underscore.
|
|
LIB$_NOCLI
|
No CLI present to perform the 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$_NOSUCHSYM
|
No such symbol. The symbol was not defined.
|
|
LIB$_UNECLIERR
|
Unexpected CLI error. The CLI returned an error status that 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 HP support representative.
|
LIB$DELETE_VM_ZONE
The Delete Virtual Memory Zone routine deletes a zone from the 32-bit
virtual address space and returns all pages on VAX systems or pagelets
on Alpha and I64 systems owned by the zone to the processwide 32-bit
page pool.
Note
No support for arguments passed by 64-bit address reference or for use
of 64-bit descriptors, if applicable, is planned for this routine.
|
Format
LIB$DELETE_VM_ZONE zone-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
zone-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Zone identifier. The zone-id is the address of a
longword that contains the identifier of a zone created by a previous
call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.
Description
LIB$DELETE_VM_ZONE deletes a zone and returns all pages on VAX systems
or pagelets on Alpha and I64 systems owned by the zone to the
processwide pool managed by LIB$GET_VM_PAGE. The pages or pagelets are
then available for reallocation by later calls to LIB$GET_VM or
LIB$GET_VM_PAGE.
It takes less time to free memory in a single operation by calling
LIB$DELETE_VM_ZONE than to individually account for and free every
block of memory that was allocated by calling LIB$GET_VM.
You must ensure that your program is no longer using any of the memory
in the zone before you call LIB$DELETE_VM_ZONE. Your program must not
do any further operations on the zone after you call LIB$DELETE_VM_ZONE.
If you specified deallocation filling when you created the zone,
LIB$DELETE_VM_ZONE will fill all of the allocated blocks that are freed.
If the zone you are deleting was created using the
LIB$CREATE_USER_VM_ZONE routine, then you must have an appropriate
action routine for the delete operation. That is, in your call to
LIB$CREATE_USER_VM_ZONE, you must have specified a
user-delete-procedure.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
An invalid
zone-id argument or a corrupted zone.
|
LIB$DELETE_VM_ZONE_64 (Alpha and I64 Only)
The Delete Virtual Memory Zone routine deletes a zone from the 64-bit
virtual address space and returns all Alpha and I64 system pagelets
owned by the zone to the processwide 64-bit page pool.
Format
LIB$DELETE_VM_ZONE_64 zone-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
zone-id
| OpenVMS usage: |
identifier |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Zone identifier. The zone-id is the address of a
quadword that contains the identifier of a zone created by a previous
call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.
Description
LIB$DELETE_VM_ZONE_64 deletes a zone and returns all pagelets on Alpha
and I64 systems owned by the zone to the processwide pool managed by
LIB$GET_VM_PAGE_64. The pagelets are then available for reallocation by
later calls to LIB$GET_VM_64 or LIB$GET_VM_PAGE_64.
It takes less time to free memory in a single operation by calling
LIB$DELETE_VM_ZONE_64 than to individually account for and free every
block of memory that was allocated by calling LIB$GET_VM_64.
You must ensure that your program is no longer using any of the memory
in the zone before you call LIB$DELETE_VM_ZONE_64. Your program must
not do any further operations on the zone after you call
LIB$DELETE_VM_ZONE_64.
If you specified deallocation filling when you created the zone,
LIB$DELETE_VM_ZONE_64 will fill all of the allocated blocks that are
freed.
If the zone you are deleting was created using the
LIB$CREATE_USER_VM_ZONE_64 routine, then you must have an appropriate
action routine for the delete operation. That is, in your call to
LIB$CREATE_USER_VM_ZONE_64, you must have specified a
user-delete-procedure.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
An invalid
zone-id argument or a corrupted zone.
|
LIB$DIGIT_SEP
The Get Digit Separator Symbol routine returns the system's digit
separator symbol.
Format
LIB$DIGIT_SEP digit-separator-string [,resultant-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
digit-separator-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Digit separator symbol returned by LIB$DIGIT_SEP. The
digit-separator-string argument is the address of a
descriptor pointing to the digit separator.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters written into
digit-separator-string, not counting padding in the
case of a fixed-length string. The resultant-length
argument is the address of an unsigned word containing the length of
the digit separator symbol. If the input string is truncated to the
size specified in the digit-separator-string
descriptor, resultant-length is set to this size.
Therefore, resultant-length can always be used by the
calling program to access a valid substring of
digit-separator-string.
Description
LIB$DIGIT_SEP returns the symbol that is used to separate groups of
three digits in the integer part of a number, for readability. A common
digit separator is a comma (,) as in 3,006,854.
LIB$DIGIT_SEP attempts to translate the logical name SYS$DIGIT_SEP as a
process, group, or system logical name. If the translation fails,
LIB$DIGIT_SEP returns a comma (,), the United States digit separator.
If the translation succeeds, the text produced is returned. Thus, a
system manager can define SYS$DIGIT_SEP as a systemwide logical name to
provide a default for all users, and an individual user with a special
need can define SYS$DIGIT_SEP as a process logical name to override the
default symbol. For example, you may want to use the European digit
separator, the period (.).
BASIC implicitly uses LIB$DIGIT_SEP.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
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 HP.
|
|
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$_STRTRU
|
Successfully completed, but the digit separator string was truncated.
|
Example
|
PROGRAM DIGIT_SEP(INPUT, OUTPUT);
{+}
{ This program uses LIB$DIGIT_SEP to return current
{ value of SYS$DIGIT_SEP.
{-}
routine LIB$DIGIT_SEP(%DESCR DIGIT_SEPSTR : VARYING [A]
OF CHAR; %REF OUT_LEN : INTEGER); EXTERN;
VAR
SEPARATOR : VARYING [256] OF CHAR;
LENGTH : INTEGER;
BEGIN
LIB$DIGIT_SEP(SEPARATOR, LENGTH);
WRITELN('104',SEPARATOR,'567',SEPARATOR,'934');
END.
|
This Pascal example demonstrates how to use LIB$DIGIT_SEP. The output
generated by this program is as follows:
LIB$DISABLE_CTRL
The Disable CLI Interception of Control Characters routine requests the
calling process's command language interpreter (CLI) to not intercept
the selected control characters when they are entered during an
interactive terminal session. LIB$DISABLE_CTRL provides the same
function as the DCL command SET NOCONTROL.
Format
LIB$DISABLE_CTRL disable-mask [,old-mask]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
disable-mask
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask indicating which control characters are not to be intercepted.
The disable-mask argument is the address of an
unsigned longword containing this bit mask.
Each of the 32 bits corresponds to one of the 32 possible control
characters. If a bit is set, the corresponding control character is no
longer intercepted by the CLI. Currently, only bits 20 and 25,
corresponding to Ctrl/T and Ctrl/Y, are recognized.
The following mask is defined in symbol libraries supplied by HP to
specify the value of disable-mask:
| Symbol |
Hex Value |
Function |
|
LIB$M_CLI_CTRLT
|
%X'00100000'
|
Disables Ctrl/T
|
|
LIB$M_CLI_CTRLY
|
%X'02000000'
|
Disables Ctrl/Y
|
If a set bit does not correspond to a character that the CLI can
intercept, LIB$DISABLE_CTRL returns an error.
old-mask
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Previous bit mask. The old-mask argument is the
address of an unsigned longword into which LIB$DISABLE_CTRL writes the
old bit mask. The old bit mask is of the same form as
disable-mask and indicates those control characters
that were previously enabled. It may therefore be given to
LIB$ENABLE_CTRL to reinstate the previous condition.
Description
The DCL and MCR CLIs can intercept the Ctrl/Y control character. The
DCL CLI can intercept the Ctrl/T character. See the HP OpenVMS DCL Dictionary for
information on how the DCL CLI processes control characters.
LIB$DISABLE_CTRL 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 those cases,
LIB$DISABLE_CTRL returns the error status LIB$_NOCLI.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid argument. A bit in
disable-mask was set that did not correspond to a
control character supported by the CLI.
|
|
LIB$_NOCLI
|
No CLI present. Either 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 that was not
recognized. This error may be caused by use of a nonstandard CLI. If
this error occurs while using the DCL or MCR CLIs, please report the
problem to your HP support representative.
|
|
