OpenVMS RTL Library (LIB$) Manual
LIB$GET_LUN
The Get Logical Unit Number routine allocates one logical unit number
from a processwide pool. If a unit is available, its number is returned
to the caller. Otherwise, an error is returned as the function value.
Format
LIB$GET_LUN logical-unit-number
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
logical-unit-number
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
write only |
| mechanism: |
by reference |
Allocated logical unit number or --1 if none was available. The
logical-unit-number argument is the address of a
longword into which LIB$GET_LUN returns the value of the allocated
logical unit. LIB$GET_LUN can allocate logical unit numbers 100 through
119 on VAX, and 100 through 299 on Alpha.
Description
LIB$GET_LUN allocates one logical unit number from a processwide pool.
If a unit is available, its number is returned to the caller.
Otherwise, an error is returned as the function value.
On VAX systems, LIB$GET_LUN reserves logical unit numbers starting at
119 and continues in descending order through 100.
On Alpha systems, LIB$GET_LUN reserves logical unit numbers 100 through
299. To maintain compatibility with VAX systems, LIB$GET_LUN reserves
logical unit numbers starting at 119 and continues in descending order
through 100. When these are exhausted, LIB$GET_LUN reserves logical
unit numbers starting at 299 and continues in descending order through
120.
LIB$GET_LUN assumes that the logical unit numbers in the range 0
through 99 may be in use by your program, but it cannot determine which
logical unit numbers are actually in use by your program.
Call LIB$GET_LUN only from Fortran or BASIC programs. Those languages
and LIB$GET_LUN share the concept of unit numbers and a similar number
space.
Note
Beware of running multiple images linked with /NOSYSSHR in the same
process and having more than one image make calls to LIB$GET_LUN. Each
image contains its own copy of the event flag bit array that is
designed to be process-wide and synchronize ownership of event flags.
Multiple calls to LIB$GET_EF could cause the same event flag to be
allocated more than once.
|
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INSLUN
|
Insufficient logical unit numbers. No logical unit numbers were
available.
|
LIB$GET_MAXIMUM_DATE_LENGTH
Given an output format and language, the Retrieve the Maximum Length of
a Date/Time String routine determines the maximum possible length for
the date-string string returned by LIB$FORMAT_DATE_TIME.
Format
LIB$GET_MAXIMUM_DATE_LENGTH date-length [,user-context] [,flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
date-length
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Receives the maximum possible length of the
date-string argument returned to LIB$FORMAT_DATE_TIME. The
date-length argument is the address of a signed
longword that receives this maximum length. The length written to
date-length reflects the greatest possible length of
an output date/time string for the currently selected output format and
natural language.
For example, if the selected output date/time format includes the
alphabetic, unabbreviated month name (assuming English as the natural
language), the longest month name (September) would have to be taken
into consideration when determining the maximum possible length of
date-string.
user-context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context variable that retains the translation context over multiple
calls to this routine. The user-context argument is
the address of an unsigned longword that contains this context. The
initial value of the context variable must be zero. Thereafter, the
user program must not write to the cell.
The user-context parameter is optional. However, if a
context cell is not passed, the routine LIB$GET_MAXIMUM_DATE_LENGTH may
abort if two threads of execution attempt to manipulate the context
area concurrently. Therefore, when calling this routine in situations
where reentrancy might occur, such as from AST level, Compaq recommends
that users specify a different context cell for each calling thread.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask that allows the user to specify whether the date, time, or
both are to be included in the calculation of the maximum date length.
The flags argument is the address of an unsigned bit
mask containing the specified values. Valid values are
LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS. The values specified for
flags must correspond to the flags
argument passed to LIB$FORMAT_DATE_TIME.
Description
The LIB$GET_MAXIMUM_DATE_LENGTH routine determines the maximum possible
length for a formatted date/time string as returned by LIB$FORMAT_DATE_TIME.
The maximum length returned takes into account the currently specified
output format and natural language; date-length
represents the maximum possible length of the string written to the
date-string argument of LIB$FORMAT_DATE_TIME.
Consider the following example, in which the output format is defined
as follows.
DEFINE LIB$DT_FORMAT LIB$DATE_FORMAT_012, LIB$TIME_FORMAT_012
|
This date/time format would appear as follows:
!MAU !DD, !Y4 !HH2:!M0 !MIU
|
Given this format, the maximum possible length for this date/time
string is calculated using the longest possible date string followed by
a space and the longest possible time string. One example that meets
these requirements is as follows (assuming English as the selected
language):
SEPTEMBER 21, 2000 11:24 PM
|
The maximum possible length of this date-string would
then be 28.
See the OpenVMS Programming Concepts Manual for a description of system date and time
operations as well as a detailed description of the format mnemonics
used in these routines.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_ABSTIMREQ
|
Absolute time required.
|
|
LIB$_DEFFORUSE
|
Default format used; unable to determine desired format.
|
|
LIB$_ENGLUSED
|
English used by default; unable to translate SYS$LANGUAGE.
|
|
LIB$_REENTRANCY
|
Reentrant invocation with same context variable.
|
|
LIB$_STRTRU
|
Output string truncated.
|
|
LIB$_UNRFORCOD
|
Unrecognized format code.
|
Any condition value returned by LIB$GET_VM.
LIB$GET_PREV_INVO_CONTEXT (Alpha Only)
The Get Previous Invocation Context routine gets the previous
invocation context of any active procedure.
A thread can obtain the invocation context of the procedure context
preceding any other procedure context using the following function
format:
Format
LIB$GET_PREV_INVO_CONTEXT invo_context
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Status value. A value of 1 indicates success. When the initial context
represents the bottom of the call chain, a value of 0 is returned.
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
modify |
| mechanism: |
by reference |
Address of an invocation context block. The given context block is
updated to represent the context of the previous (calling) frame.
For the purposes of this function, the minimum fields of an invocation
block that must be defined are those IREG and FREG fields corresponding
to registers used by a context whether the registers are preserved or
not. Note that the invocation context blocks written by the routines
specified in these sections define all possible fields in a context
block. Such context blocks satisfy this minimum requirement.
Description
LIB$GET_PREV_INVO_CONTEXT gets the previous invocation context of any
active procedure.
See the OpenVMS Calling Standard manual for additional information.
Condition Values Returned
None.
LIB$GET_PREV_INVO_HANDLE (Alpha 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 OpenVMS Calling Standard manual for additional 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 Compaq (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 Compaq 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 Compaq support representative.
|
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.
|
|
