Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## 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.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_025.HTML