Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

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 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 Digital support representative.

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 Compaq (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 Compaq.
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 Compaq support representative.

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

The Delete Virtual Memory Zone routine deletes a zone from the 64-bit virtual address space and returns all Alpha 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 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.

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

104,567,934

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 Compaq 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 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 Compaq support representative.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_012.HTML