Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

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

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

## LIB$DELETE_VM_ZONE_64 (Alpha Only)

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

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_013.HTML