 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$GET_PREV_INVO_HANDLE (Alpha and I64 Only)
The Get Previous Invocation Handle routine gets the previous invocation
handle of any active procedure.
A thread can obtain an invocation handle of the procedure context
preceding that of a specified procedure context by using the following
function format.
Format
LIB$GET_PREV_INVO_HANDLE invo_handle
RETURNS
| OpenVMS usage: |
invo_handle |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
An invocation handle for the invocation context that is previous to
that which was specified as the target.
Argument
invo_handle
| OpenVMS usage: |
invo_handle |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
An invocation handle that represents a target invocation context.
Description
LIB$GET_PREV_INVO_HANDLE gets the previous invocation handle of any
active procedure.
See the HP OpenVMS Calling Standard manual for more information.
Condition Values Returned
None.
LIB$GET_SYMBOL
The Get Value of CLI Symbol routine requests the calling process's
command language interpreter (CLI) to return the value of a CLI symbol
as a string. LIB$GET_SYMBOL then returns the string to the caller.
Optionally, LIB$GET_SYMBOL can return the length of the returned value
and the table in which the symbol was found.
Format
LIB$GET_SYMBOL symbol ,resultant-string [,resultant-length]
[,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 for which LIB$GET_SYMBOL searches. The
symbol argument is the address of a descriptor
pointing to the name of the symbol. LIB$GET_SYMBOL converts the symbol
name to uppercase and removes trailing blanks before the search. 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.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Value of the returned symbol. The resultant-string
argument is the address of a descriptor pointing to a character string
into which LIB$GET_SYMBOL writes the value of the symbol.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the symbol value returned by LIB$GET_SYMBOL. The
resultant-length argument is the address of an
unsigned word integer into which LIB$GET_SYMBOL writes the length.
table-type-indicator
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Indicator of which table contained the symbol. The
table-type-indicator argument is the address of a
signed longword integer into which LIB$GET_SYMBOL writes the table
indicator.
Possible values of the table indicator are listed below.
| Symbolic Name |
Value |
Table |
|
LIB$K_CLI_LOCAL_SYM
|
1
|
Local symbol table
|
|
LIB$K_CLI_GLOBAL_SYM
|
2
|
Global symbol table
|
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.
Description
LIB$GET_SYMBOL first searches the local symbol table for the symbol
name, then searches the global symbol table. Numeric values are
converted to an ASCII representation of a signed decimal number before
being returned.
LIB$GET_SYMBOL is supported for use with the DCL command language
interpreter. 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 get the symbol. In that case, LIB$GET_SYMBOL
returns the error status LIB$_NOCLI.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_STRTRU
|
Routine successfully completed; string truncated. The destination
string could not contain all the characters in the symbol value.
|
|
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 obtain enough virtual memory
to perform the function. This may be caused by having too many symbols
defined. Deleting some symbol definitions may relieve the situation.
|
|
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$_INVSYMNAM
|
Invalid symbol name. The symbol name contained more than 255 characters
or did not begin with a letter or dollar sign ($).
|
|
LIB$_NOCLI
|
No CLI present. 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 in either the local or
global symbol table.
|
|
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.
|
LIB$GET_UIB_INFO
Returns information from the unwind information block (UIB).
Format
LIB$GET_UIB_INFO uib_va [,gp_value] [,uw_desc_va] [,uw_desc_len]
[,handler_fv] [,ossd_va] [,lsda_va]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
uib_va
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a quadword that contains the virtual address of an unwind
information block (UIB).
gp_value
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a quadword that contains the GP value that must be added to
the UIB condition handler value. Must be specified if
handler_fv is specified.
uw_desc_va
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write |
| mechanism: |
by reference |
Address of a quadword to store the virtual address of the unwind
descriptor area. If none is present, then zero is returned. This is an
optional argument.
un_desc_len
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write |
| mechanism: |
by reference |
Address of a quadword to store the length (in bytes) of the unwind
descriptor area. If none are present, then zero is returned. This is an
optional argument.
handler_fv
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write |
| mechanism: |
by reference |
Address of a quadword to store the function value of the condition
handler. If none is present, then zero is returned. This is an optional
argument.
ossd_va
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write |
| mechanism: |
by reference |
Address of a quadword to store the address of the operating
system-specific data area. If none is present, then zero is returned.
This is an optional argument.
lsda_va
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write |
| mechanism: |
by reference |
Address of a quadword to store the address of the language-specific
data area (LSDA). If none is present, then zero is returned. This is an
optional argument.
Description
Takes in the address of an uwind information block (UIB) and the GP
value for a routine and returns the addresses of the start of the
unwind descriptors (if any), the handler function descriptor (if any),
and the operating system-specific data area (if any). The size in bytes
of the unwind descriptors is also returned.
Related Services
SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE, SYS$GET_UNWIND_ENTRY_INFO,
Condition Values Returned
|
SS$_NORMAL
|
Routine completed successfully.
|
|
LIB$_INVARG
|
Bad UIB virtual address.
|
LIB$GET_USERS_LANGUAGE
The Return the User's Language routine determines the user's choice of
a natural language. The choice is determined by translating the logical
SYS$LANGUAGE.
Format
LIB$GET_USERS_LANGUAGE language
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
language
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Receives the translation of SYS$LANGUAGE. The language
argument is the address of a descriptor pointing to this language name.
Description
The LIB$GET_USERS_LANGUAGE routine translates the logical SYS$LANGUAGE
and returns the user's choice of a natural language. If the logical
SYS$LANGUAGE does not translate for some reason, then the language
defaults to English and the status LIB$_ENGLUSED is returned.
If a failure or truncation occurs while copying the language name to
the language string argument, that error status
overrides the LIB$_ENGLUSED or SS$_NORMAL status.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_ENGLUSED
|
English used by default; unable to translate SYS$LANGUAGE.
|
Any condition value returned by LIB$SCOPY_R_DX.
LIB$GET_VM
The Allocate Virtual Memory routine allocates a specified number of
contiguous bytes in the program region and returns the 32-bit virtual
address of the first byte allocated.
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$GET_VM number-of-bytes, base-address [,zone-id]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-bytes
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of contiguous bytes that LIB$GET_VM allocates. The
number-of-bytes argument is the address of a longword
integer containing the number of bytes. LIB$GET_VM allocates enough
memory to satisfy the request. Your program should not reference an
address before the first byte address allocated
(base-address) or beyond the last byte allocated
(base-address + number-of-bytes - 1)
since that space may be assigned to another routine. The value of
number-of-bytes must be greater than zero.
base-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
First virtual address of the contiguous block of bytes allocated by
LIB$GET_VM. The base-address argument is the address
of an unsigned longword containing this base address.
zone-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The zone-id argument is the address of a longword that
contains a zone identifier created by a previous call to
LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE. This argument is
optional. If zone-id is omitted or if the longword
contains the value 0, the 32-bit default zone is used.
Description
LIB$GET_VM satisfies an allocation request by reusing free memory in
the zone, or by obtaining additional memory from the processwide 32-bit
page pool managed by LIB$GET_VM_PAGE.
LIB$GET_VM rounds up the value of number-of-bytes to a
multiple of the block-size specified for the zone. The
first byte allocated is aligned on the boundary specified by the
alignment value for the zone.
If you specified allocation filling when you created the zone,
LIB$GET_VM will fill each byte allocated. Otherwise, LIB$GET_VM does
not initialize the memory and its contents are unpredictable.
All memory allocated by LIB$GET_VM has user mode read/write access,
even if the call to LIB$GET_VM was made from a more privileged access
mode.
The space allocated by successive calls to LIB$GET_VM may be
noncontiguous because another routine can call LIB$GET_VM between your
calls. If AST interrupts occur, LIB$GET_VM may allocate space to
another routine between execution of any two statements in your
program. Even if successive calls to LIB$GET_VM return two contiguous
blocks, you must not combine them into one large block that is freed by
a single call to LIB$FREE_VM.
LIB$GET_VM is fully reentrant, so it may be called by routines
executing at AST level or in an Ada multitasking environment.
Your program must retain the address of the allocated area. This allows
you to access or deallocate the space later.
If the zone you are getting was created using the
LIB$CREATE_USER_VM_ZONE routine, then you must have an appropriate
action routine for the get operation. That is, in your call to
LIB$CREATE_USER_VM_ZONE, you must have specified a
user-get-routine.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Invalid
zone-id or a corrupt zone.
|
|
LIB$_BADBLOSIZ
|
Bad block size. The value of
number-of-bytes was less than or equal to 0. For the
fixed-size blocks algorithm, LIB$_BADBLOSIZ can also be generated if
the value of
algorithm-argument specified in the call to
LIB$CREATE_VM_ZONE is less than
number-of-bytes.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. The request required more dynamic memory
than was available from the operating system. No partial allocation is
made in this case.
|
|
LIB$_PAGLIMEXC
|
Allocation exceeds the
page-limit, set when the zone was create.
|
LIB$GET_VM_64 (Alpha and I64 Only)
The Allocate Virtual Memory routine allocates a specified number of
contiguous bytes in the program region and returns the 64-bit virtual
address of the first byte allocated.
Format
LIB$GET_VM_64 number-of-bytes, base-address [,zone-id]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-bytes
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of contiguous bytes that LIB$GET_VM_64 allocates. The
number-of-bytes argument is the address of a quadword
integer containing the number of bytes. LIB$GET_VM_64 allocates enough
memory to satisfy the request. Your program should not reference an
address before the first byte address allocated
(base-address) or beyond the last byte allocated
(base-address + number-of-bytes - 1)
since that space may be assigned to another routine. The value of
number-of-bytes must be greater than zero.
base-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
First virtual address of the contiguous block of bytes allocated by
LIB$GET_VM_64. The base-address argument is the
address of an unsigned quadword containing this base address.
zone-id
| OpenVMS usage: |
identifier |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The zone-id argument is the address of a quadword that
contains a zone identifier created by a previous call to
LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64. This argument is
optional. If zone-id is omitted or if the quadword
contains the value 0, the 64-bit default zone is used.
Description
LIB$GET_VM_64 satisfies an allocation request by reusing free memory in
the zone, or by obtaining additional memory from the processwide 64-bit
page pool managed by LIB$GET_VM_PAGE_64.
LIB$GET_VM_64 rounds up the value of number-of-bytes
to a multiple of the block-size specified for the
zone. The first byte allocated is aligned on the boundary specified by
the alignment value for the zone.
If you specified allocation filling when you created the zone,
LIB$GET_VM_64 will fill each byte allocated. Otherwise, LIB$GET_VM_64
does not initialize the memory and its contents are unpredictable.
All memory allocated by LIB$GET_VM_64 has user mode read/write access,
even if the call to LIB$GET_VM_64 was made from a more privileged
access mode.
The space allocated by successive calls to LIB$GET_VM_64 may be
noncontiguous because another routine can call LIB$GET_VM_64 between
your calls. If AST interrupts occur, LIB$GET_VM_64 may allocate space
to another routine between execution of any two statements in your
program. Even if successive calls to LIB$GET_VM_64 return two
contiguous blocks, you must not combine them into one large block that
is freed by a single call to LIB$FREE_VM_64.
LIB$GET_VM_64 is fully reentrant, so it may be called by routines
executing at AST level or in an Ada multitasking environment.
Your program must retain the address of the allocated area. This allows
you to access or deallocate the space later.
If the zone you are getting was created using the
LIB$CREATE_USER_VM_ZONE_64 routine, then you must have an appropriate
action routine for the get operation. That is, in your call to
LIB$CREATE_USER_VM_ZONE_64, you must have specified a
user-get-routine.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Invalid
zone-id or a corrupt zone.
|
|
LIB$_BADBLOSIZ
|
Bad block size. The value of
number-of-bytes was less than or equal to 0. For the
fixed-size blocks algorithm, LIB$_BADBLOSIZ can also be generated if
the value of
algorithm-argument specified in the call to
LIB$CREATE_VM_ZONE_64 is less than
number-of-bytes.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. The request required more dynamic memory
than was available from the operating system. No partial allocation is
made in this case.
|
|
LIB$_PAGLIMEXC
|
Allocation exceeds the
page-limit, set when the zone was create.
|
|
