HP OpenVMS systems documentation

The Get Virtual Memory Page routine allocates a specified number of contiguous pages on VAX systems or pagelets on Alpha and I64 systems of memory in the program region and returns the virtual address of the first allocated page on VAX or pagelet on Alpha or I64.

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_PAGE number-of-pages ,base-address

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

number-of-pages

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

Number of pages on VAX systems or pagelets on Alpha and I64 systems. The number-of-pages argument is the address of a longword integer that specifies the number of contiguous pages on VAX systems or pagelets on Alpha and I64 systems to be allocated. The value of number-of-pages must be greater than 0.

base-address

OpenVMS usage:	address
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Block address. The base-address argument is the address of a longword that is set to the address of the first byte of the newly allocated block of pages on VAX systems or pagelets on Alpha and I64 systems.

Description

LIB$GET_VM_PAGE allocates blocks of contiguous (512 byte) pages on VAX systems and pagelets on Alpha and I64 systems in the program region. LIB$GET_VM_PAGE manages a processwide pool of free pages. If there are not enough contiguous free pages or pagelets to satisfy an allocation request, additional pages are created by calling the system service $EXPREG. All memory allocated by LIB$GET_VM_PAGE is pagelet aligned; that is, the low-order nine bits of the base address are zero.

All memory allocated by LIB$GET_VM_PAGE has user-mode read/write access, even if the call to LIB$GET_VM_PAGE is made from a more privileged access mode.

The contents of memory allocated by LIB$GET_VM_PAGE are unpredictable. Your program must assign values to all locations that it uses.

LIB$GET_VM_PAGE is designed for request sizes ranging from one page or pagelet to a few hundred pages or pagelets. For very large request sizes (over 1000 pages or pagelets in a single request), you should call the system service $EXPREG.

LIB$GET_VM_PAGE is fully reentrant, so it can be called by routines executing at AST level or in an Ada multitasking environment.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_BADBLOSIZ	The value of the number-of-pages argument is less than or equal to 0.
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.

The Get Virtual Memory Page routine allocates a specified number of contiguous Alpha or I64 pagelets of memory in the program region and returns the virtual address of the first allocated pagelet.

Format

LIB$GET_VM_PAGE_64 number-of-pages ,base-address

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

number-of-pages

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	read only
mechanism:	by reference

Number of Alpha or I64 pagelets. The number-of-pages argument is the address of a quadword integer that specifies the number of contiguous Alpha or I64 pagelets to be allocated. The value of number-of-pages must be greater than 0.

base-address

OpenVMS usage:	address
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

Block address. The base-address argument is the address of a quadword that is set to the address of the first byte of the newly allocated block of Alpha or I64 pagelets.

Description

LIB$GET_VM_PAGE_64 allocates blocks of contiguous Alpha or I64 pagelets in the program region. LIB$GET_VM_PAGE_64 manages a processwide pool of free pagelets. If there are not enough contiguous free pagelets to satisfy an allocation request, additional pagelets are created by calling the system service $EXPREG_64. All memory allocated by LIB$GET_VM_PAGE_64 is aligned to physical page size.

All memory allocated by LIB$GET_VM_PAGE_64 has user-mode read/write access, even if the call to LIB$GET_VM_PAGE_64 is made from a more privileged access mode.

The contents of memory allocated by LIB$GET_VM_PAGE_64 are unpredictable. Your program must assign values to all locations that it uses.

LIB$GET_VM_PAGE_64 is fully reentrant, so it can be called by routines executing at AST level or in an Ada multitasking environment.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_BADBLOSIZ	The value of the argument number-of-pages is less than or equal to 0.
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.

The Create Invocation Context routine allocates an invocation context block from heap storage and initializes it.

Format

LIB$I64_CREATE_INVO_CONTEXT [malloc] [,free] [,ident]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

malloc

OpenVMS usage:	function_value
type:	procedure
access:	read
mechanism:	by value

A procedure reference for a user callback routine that allocates memory. This is an optional argument. The default is to use an implementation of the C RTL routine malloc. If specified, this routine is used to allocate the invocation context block field LIBICB$PH_UO_MALLOC for use during the stack walk.

free

OpenVMS usage:	function_value
type:	procedure
access:	read
mechanism:	by value

A procedure reference for a user callback routine that deallocates memory. This value is placed in the invocation context block field LIBICB$PH_UO_FREE. This is an optional argument; however, it must be specified if malloc is specified. The default is to use an implementation of the C RTL routine free.

ident

OpenVMS usage:	user_value
type:	quadword
access:	read
mechanism:	by value

Specifies a user ident value to be placed in the invocation context block LIBICB$IH_UO_IDENT field. In turn, this value is passed to the malloc and free routines. This is an optional argument; the default value is zero.

Description

LIB$I64_CREATE_INVO_CONTEXT simplifies creating and properly initializing an invocation context block. The routine allocates an invocation context block from heap storage and initializes it. Users of this routine should call LIB$I64_FREE_INVO_CONTEXT when the invocation context block is no longer required.

This routine sets the cache unwind flag LIBICB$V_UO_FLAG_CACHE_UNWIND in the invocation context block to speed up the stack walk. Do not use this routine in conjunction with LIB$I64_INIT_INVO_CONTEXT, as the same initialization is performed by both routines.

Condition Values Returned

0	Indicates failure.
any non-zero value	Represents the address of the allocated invocation context block.

The Free Invocation Context Block routine deallocates an invocation context block that was previously allocated.

Format

LIB$I64_FREE_INVO_CONTEXT invo_context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	modify only
mechanism:	by reference

Address of an invocation context block.

Description

LIB$I64_FREE_INVO_CONTEXT deallocates an invocation context block that was previously allocated using LIB$I64_CREATE_INVO_CONTEXT. This routine calls LIB$I64_PREV_INVO_END as a convenience.

Condition Values Returned

None.

The Get Current Invocation Context routine gets the invocation context of a current procedure.

Format

LIB$I64_GET_CURR_INVO_CONTEXT invo_context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	modify only
mechanism:	by reference

Address of an invocation context block into which the procedure context of the caller will be written.

Description

LIB$I64_GET_CURR_INVO_CONTEXT gets the invocation context of a current procedure. The invocation context block must be properly initialized as described in the HP OpenVMS Calling Standard manual before calling this routine.

Condition Values Returned

0	Facilitates use in the implementation of the C language unwind setjmp or longjmp function. Check the LIBICB$L_ALERT_CODE field of the invocation context block for further status indication.

The Get Current Invocation Handle routine gets the invocation handle for the current procedure.

Format

LIB$I64_GET_CURR_INVO_HANDLE invo_handle

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

invo_handle

OpenVMS usage:	invo_handle
type:	quadword
access:	write only
mechanism:	by reference

Address of a quadword into which the invocation handle of the caller will be written.

Description

LIB$I64_GET_CURR_INVO_HANDLE gets the invocation handle for the current procedure.

Condition Values Returned

0	The initial context represents the bottom of the call stack.
1	Indicates success.
3	The current operation completed without error, but a stack corruption was detected at the next level down.

The Get Floating-Point Register routine copies the value of the floating-point register.

Format

LIB$I64_GET_FR invo_context, index, fr_copy

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	read
mechanism:	by reference

Address of a valid invocation context block.

index

OpenVMS usage:	index
type:	longword
access:	read
mechanism:	by value

Floating point register index.

fr_copy

OpenVMS usage:	floating-point value
type:	octaword
access:	write
mechanism:	by value

Address of an octaword to receive the contents of the specified floating-point register.

Description

Given an invocation context block and floating-point register index such that 0 <= index < 128, LIB$I64_GET_FR copies the register value to fr_copy. For example, an index value of 4 fetches the value, which represents the contents of F4 for the context.

LIB$I64_GET_FR returns failure status if the index represents a scratch register whose contents have not been realized.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Get Invocation Context Block Value routine fetches the invocation context block IREG[4] value.

Format

LIB$I64_GET_GR invo_context, index, gr_copy

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:	read
mechanism:	by reference

Address of a valid invocation context block.

index

OpenVMS usage:	index
type:	longword
access:	read
mechanism:	by value

Index into the IREG array of the invocation context block.

gr_copy

OpenVMS usage:	floating-point value
type:	octaword
access:	write
mechanism:	by value

Address of an octaword to receive the value from the invocation context block.

Description

Given an invocation context block and general register index such that 0 <= index < 128, LIB$I64_GET_GR copies the register value to gr_copy, for example, index 4 fetches the invocation context block IREG[4] value, which represents the contents of R4 for the context.

If the register represented by index has its corresponding NaT bit set, the read succeeds and the return status is set to 3. If the register represented by index lies beyond the allocated general registers, the read fails and gr_copy is unchanged. That is, the highest allowed index is 32 + ICB.CFM.SOF - 1.

LIB$I64_GET_GR fails if the index represents a scratch register whose contents have not been realized.

Condition Values Returned

0	Indicates failure.
1	Indicates success, and that the NaT bit was clear.
3	Indicates success, and that the NaT bit was set.

The Get Invocation Context routine gets the invocation context of any active procedure.

Format

LIB$I64_GET_INVO_CONTEXT invo_handle, invo_context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

invo_handle

OpenVMS usage:	invo_handle
type:	quadword
access:	modify 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.

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$I64_GET_INVO_CONTEXT gets the invocation context of any active procedure.

Note The invocation context block must be properly initialized as described in the HP OpenVMS Calling Standard manual before calling this routine.

Condition Value Returned

0	Facilitates use in the implementation of the C language unwind setjmp or longjmp function. Check the LIBICB$L_ALERT_CODE field of the invocation context block for further status indication.