Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

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.

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, Digital 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, 1994 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.

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.

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.

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.

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.

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_024.HTML