|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
The Get Invocation Context routine gets the invocation context of any active procedure.
LIB$GET_INVO_CONTEXT invo_handle, invo_context
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
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.
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.
0 Indicates failure. 0 Indicates success.
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.
LIB$GET_INVO_HANDLE invo_context
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.
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.
LIB$GET_INVO_HANDLE gets an invocation handle of any active procedure.See the HP OpenVMS Calling Standard manual for additional information.
None.
The Get Logical Name routine calls the system service routine $TRNLNM to return information about a logical name.
LIB$GET_LOGICAL logical-name [,resultant-string] [,resultant-length] [,table-name] [,max-index] [,index] [,acmode] [,flags]
OpenVMS usage: cond_value type: longword access: write only mechanism: by value
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.
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.
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.
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.
LIB$GET_LUN logical-unit-number
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
SS$_NORMAL Routine successfully completed. LIB$_INSLUN Insufficient logical unit numbers. No logical unit numbers were available.
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.
LIB$GET_MAXIMUM_DATE_LENGTH date-length [,user-context] [,flags]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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_012This date/time format would appear as follows:
!MAU !DD, !Y4 !HH2:!M0 !MIUGiven 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 PMThe 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.
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.
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.
LIB$GET_PREV_INVO_CONTEXT invo_context
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
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.
LIB$GET_PREV_INVO_CONTEXT gets the previous invocation context of any active procedure.See the HP OpenVMS Calling Standard manual for more information.
0 The initial context represents the bottom of the call chain. 1 Indicates success.
| Previous | Next | Contents | Index |