 |
HP OpenVMS RTL Library (LIB$) Manual
Any RMS condition value returned by $GET.
Any condition value returned by LIB$GET_VM, LIB$GET_VM_64,
LIB$SCOPY_R_DX, or LIB$SCOPY_R_DX_64.
LIB$GET_INVO_CONTEXT (Alpha and I64 Only)
The Get Invocation Context routine gets the invocation context of any
active procedure.
Format
LIB$GET_INVO_CONTEXT invo_handle, invo_context
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
invo_handle
| OpenVMS usage: |
invo_handle |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Handle for the desired invocation. Returned by LIB$GET_INVO_HANDLE.
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
write only |
| mechanism: |
by reference |
Address of an invocation context block into which the procedure context
of the frame specified by invo_handle will be written.
Description
LIB$GET_INVO_CONTEXT gets the invocation context of any active
procedure.
Note
If invo_handle does not represent any procedure
context in the active call chain, the new contents of the invocation
context block are unpredictable.
|
See the HP OpenVMS Calling Standard manual for additional information.
Condition Values Returned
|
0
|
Indicates failure.
|
|
0
|
Indicates success.
|
LIB$GET_INVO_HANDLE (Alpha and I64 Only)
The Get Invocation Handle routine gets an invocation handle of any
active procedure.
A thread can obtain an invocation handle corresponding to any
invocation context block by using the following function format.
Format
LIB$GET_INVO_HANDLE invo_context
RETURNS
| OpenVMS usage: |
invo_handle |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Invocation handle of the invocation context that was passed. If the
returned value is LIB$K_INVO_HANDLE_NULL, the invocation context that
was passed was invalid.
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
read only |
| mechanism: |
by reference |
Address of an invocation context block. Here, only the frame pointer
and stack pointer fields of an invocation context block must be defined.
Description
LIB$GET_INVO_HANDLE gets an invocation handle of any active procedure.
See the HP OpenVMS Calling Standard manual for additional information.
Condition Values Returned
None.
LIB$GET_LOGICAL
The Get Logical Name routine calls the system service routine $TRNLNM
to return information about a logical name.
Format
LIB$GET_LOGICAL logical-name [,resultant-string] [,resultant-length]
[,table-name] [,max-index] [,index] [,acmode] [,flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword |
| access: |
write only |
| mechanism: |
by value |
Arguments
logical-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Logical name for which LIB$GET_LOGICAL searches. The
logical-name argument is the address of a descriptor
pointing to the logical name string.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Logical name equivalent returned. The resultant-string
argument is the address of a descriptor pointing to a character string
into which LIB$GET_LOGICAL writes the equivalence name of the logical.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the equivalence name string returned by LIB$GET_LOGICAL. The
resultant-length argument is the address of an
unsigned word integer into which LIB$GET_LOGICAL writes the length.
table-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the table in which to search for the logical name. The
table-name argument contains the address of a
descriptor pointing to a character string which contains the table
name. If no table is specified, LNM$FILE_DEV is used.
max-index
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Largest equivalence name index. Each equivalence name for the logical
name has an index associated with it. The max-index
argument is the address of a signed longword integer into which
LIB$GET_LOGICAL write the value. If no equivalence names (and,
therefore, no index values) exist, LIB$GET_LOGICAL returns a value of
-1.
index
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Equivalence name index value. LIB$GET_LOGICAL will return the
equivalence name string that has the specified index value. The
index argument is the address of an unsigned longword
integer specifying the index value.
acmode
| OpenVMS usage: |
access_mode |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Access mode to be used in the translation. The acmode
argument is the address of a byte specifying the access mode. The
$PSLDEF macro defines symbolic names for the four access modes.
When you specify the acmode argument, all names at
access modes which are less privileged than the specified access mode
are ignored.
If you do not specify acmode, the translation is
performed without regard to access mode; however, the translation
process proceeds from the outermost to the innermost access modes.
Thus, if two logical names with the same name, but at different access
modes, exist in the same table, the name with the outermost access mode
is translated.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags controlling the search for the logical name. The
flags argument is the address of a longword integer
that contains the control flags. The $LNMDEF macro defines these flags.
Currently only bit 0 of this argument is used.
| Bit |
Value |
Description |
|
0
|
LNM$M_CASE_BLIND
|
If set, LIB$GET_LOGICAL does not distinguish between uppercase and
lowercase letters in the logical name to be translated.
|
This is an optional argument. If omitted the default is 0.
Description
LIB$GET_LOGICAL provides a simplified interface to the $TRNLNM system
service. It provides most of the features found in $TRNLNM with some
additional benefits. For string arguments, all string classes supported
by the Run-Time Library are understood. The list of item descriptors,
which may be difficult to construct in high-level languages, is handled
internally by LIB$GET_LOGICAL.
See the description of the $TRNLNM system service in the HP OpenVMS System Services Reference Manual
for more information.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_ACCVIO
|
Access violation. Cannot access the location specified.
|
|
SS$_BADPARAM
|
Bad parameter value.
|
|
SS$_IVLOGNAM
|
Invalid logical name. The logical name or its value contained more than
255 characters.
|
|
SS$_IVLOGTAB
|
Invalid logical name table.
|
|
SS$_NOLOGNAM
|
The logical name was not found in the specified table.
|
|
SS$_NOPRIV
|
No privileges for attempted operation.
|
|
SS$_TOOMANYNAM
|
Logical name translation exceeded allowed depth.
|
|
LIB$_INVARG
|
Required argument is missing.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
|
LIB$_STRTRU
|
Success, but source string truncated.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
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 and I64.
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 and I64 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, HP 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 HP 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 and I64 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 |
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 HP OpenVMS Calling Standard manual for more information.
Condition Values Returned
|
0
|
The initial context represents the bottom of the call chain.
|
|
1
|
Indicates success.
|
|
