|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
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.
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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 HP 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 HP 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 HP 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.
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 HP 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 HP OpenVMS DCL Dictionary for a description of the DEFINE command.
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 HP support representative.
!+
! 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)
The Set Value of CLI Symbol routine requests the calling process's command language interpreter (CLI) to define or redefine a CLI symbol.
LIB$SET_SYMBOL symbol ,value-string [,table-type-indicator]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
symbol
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Name of the symbol to be defined or modified by LIB$SET_SYMBOL. The symbol argument is the address of a descriptor pointing to this symbol string. If you redefine a previously defined CLI symbol, the symbol value is modified to the new value that you provide.The symbol name is converted to uppercase and trailing blanks are removed before use. The symbol argument must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 characters.
value-string
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Value to be given to the symbol. The value-string argument is the address of a descriptor pointing to this value string.Trailing blanks are not removed from the value string before use. The maximum length of value-string is 1024 characters. Integer values are not allowed; LIB$SET_SYMBOL is intended to set string CLI symbols, not integer CLI symbols.
table-type-indicator
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Indicator of the table that will contain the defined symbol. The table-type-indicator argument is the address of a signed longword integer that is this table indicator.If omitted, the local symbol table is used. The following are possible values for table-type-indicator:
Symbolic Name Value Table Used LIB$K_CLI_LOCAL_SYM 1 Local symbol table LIB$K_CLI_GLOBAL_SYM 2 Global symbol table
LIB$SET_SYMBOL requests the calling process's CLI to define or redefine a CLI symbol.CLI symbols created using LIB$SET_SYMBOL may be inaccessible by other CLI commands. To avoid this situation, make sure that your symbol names are alphanumeric and that the first character is alphabetic. LIB$SET_SYMBOL is intended to set string CLI symbols, not integer CLI symbols.
LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined as global symbols and in symbol libraries supplied by HP (macro or module name $LIBCLIDEF).
This routine is supported for use with the DCL CLI. If used with the MCR CLI, the error status LIB$_NOCLI will be returned. If an image is run directly as a subprocess or as a detached process, there is no CLI present to perform this function. In this case, the error status LIB$_NOCLI is returned.
SS$_NORMAL Routine successfully completed. LIB$_AMBSYMDEF Ambiguous symbol definition. The symbol name you want to define is ambiguous when compared with existing symbol names. This condition might arise if abbreviated symbols have been defined previously. See the HP OpenVMS DCL Dictionary for more information on abbreviated symbols. 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 HP support representative. LIB$_INSCLIMEM Insufficient CLI memory. The CLI could not get enough virtual memory to assign another symbol. This condition may be caused by having too many symbols defined; deleting some symbol definitions may make enough room for the new symbol. 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 or the length of value-string was greater than 1024 characters. LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field. LIB$_INVSYMNAM Invalid symbol name. The length of symbol was greater than 255 characters or symbol did not begin with a letter. 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 HP support representative.
!+
! Initialize value and symbol name
!-
SYMBOL$ = 'MY_SYM'
SETVAL$ = 'ON'
CALL LIB$SET_SYMBOL (SYMBOL$, SETVAL$)
END
|
The BASIC program above sets the symbol MY_SYM to ON. This value can be displayed after the program is run with SHOW SYMBOL as follows:
$ SHOW SYMBOL MY_SYM "MY_SYM" = "ON" (LNM$PROCESS_TABLE)
The Free One Dynamic String routine returns the dynamically allocated storage for a dynamic string.
LIB$SFREE1_DD descriptor-address
Corresponding JSB Entry Point
LIB$SFREE1_DD6
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
descriptor-address
OpenVMS usage: descriptor type: quadword (unsigned) access: modify mechanism: by reference
Dynamic descriptor specifying the area to be deallocated. The descriptor-address argument is the address of an unsigned quadword that is this descriptor. The descriptor is assumed to be dynamic and its class field is not checked.
Before a routine deallocates a dynamic descriptor, it must use LIB$SFREE1_DD or LIB$SFREEN_DD to deallocate the string storage space specified by the dynamic descriptor. Otherwise, string storage is not deallocated and your program can run out of memory.This routine deallocates the described string space and flags the descriptor as describing no string at all. The descriptor's POINTER and LENGTH fields contain zero (0).
SS$_NORMAL Routine successfully completed. LIB$_FATERRLIB Fatal internal error.
The Free One or More Dynamic Strings routine returns one or more dynamic strings to free storage.
LIB$SFREEN_DD number-of-descriptors ,first-descriptor-array
Corresponding JSB Entry Point
LIB$SFREEN_DD6
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
number-of-descriptors
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Number of adjacent descriptors freed by LIB$SFREEN_DD. The number-of-descriptors argument contains the address of an unsigned longword that is this number. The deallocated area is returned to free storage.first-descriptor-array
OpenVMS usage: descriptor_array type: quadword (unsigned) access: modify mechanism: by reference, array reference
First descriptor of an array of descriptors. The first-descriptor-array argument contains the address of this first descriptor. The descriptors are assumed to be dynamic, and their class fields are not checked.The descriptor array must contain all 32-bit descriptors or all 64-bit descriptors. They cannot be mixed.
Before a routine that allocates space returns to its caller, it must use LIB$SFREE1_DD or LIB$SFREEN_DD to deallocate the string storage space specified by any descriptors located in the stack. Otherwise, space is not deallocated and your program could run out of virtual memory.LIB$SFREEN_DD deallocates the described string space and flags each descriptor as describing no string at all by setting the descriptor's POINTER and LENGTH fields to 0 (zero).
SS$_NORMAL Routine successfully completed. LIB$_FATERRLIB Fatal internal error.
The Get One Dynamic String routine allocates dynamic virtual memory to the string descriptor you specify.
LIB$SGET1_DD word-integer-length ,descriptor-part
Corresponding JSB Entry Point
LIB$SGET1_DD_R6
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
word-integer-length
OpenVMS usage: word_unsigned type: word (unsigned) access: read only mechanism: by reference
Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_DD. The word-integer-length argument is the address of an unsigned word that contains this number. The amount of storage allocated may be rounded up automatically.descriptor-part
OpenVMS usage: quadword_unsigned type: quadword (unsigned) access: write only mechanism: by reference
Descriptor of the dynamic string to which LIB$SGET1_DD allocates the dynamic virtual memory. The descriptor-part argument contains the address of this descriptor.The descriptor-part argument must contain the address of a dynamic string descriptor; LIB$SGET1_DD returns an unpredictable result if any other type of descriptor is specified by this argument.
The descriptor CLASS field is not checked but is set to dynamic (2). The LENGTH field is set to word-integer-length, and the POINTER field points to the string area allocated.
LIB$SGET1_DD is similar to LIB$SCOPY_DXDX except that no source string is copied. You can write anything you want in the allocated area.If descriptor-part already has dynamic memory allocated to it, but the amount allocated is less than word-integer-length, that space is deallocated before LIB$SGET1_DD allocates new space.
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 your HP support representative. LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.
| Previous | Next | Contents | Index |