OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$GET_VM_64 (Alpha Only)

The Allocate Virtual Memory routine allocates a specified number of contiguous bytes in the program region and returns the 64-bit virtual address of the first byte allocated.

Format

LIB$GET_VM_64 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: quadword_signed

type: quadword integer (signed)

access: read only

mechanism: by reference

Number of contiguous bytes that LIB$GET_VM_64 allocates. The number-of-bytes argument is the address of a quadword integer containing the number of bytes. LIB$GET_VM_64 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: quadword (unsigned)

access: write only

mechanism: by reference

First virtual address of the contiguous block of bytes allocated by LIB$GET_VM_64. The base-address argument is the address of an unsigned quadword containing this base address.
zone-id

OpenVMS usage: identifier

type: quadword (unsigned)

access: read only

mechanism: by reference

The zone-id argument is the address of a quadword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64. This argument is optional. If zone-id is omitted or if the quadword contains the value 0, the 64-bit default zone is used.

Description

LIB$GET_VM_64 satisfies an allocation request by reusing free memory in the zone, or by obtaining additional memory from the processwide 64-bit page pool managed by LIB$GET_VM_PAGE_64.
LIB$GET_VM_64 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_64 will fill each byte allocated. Otherwise, LIB$GET_VM_64 does not initialize the memory and its contents are unpredictable.
All memory allocated by LIB$GET_VM_64 has user mode read/write access, even if the call to LIB$GET_VM_64 was made from a more privileged access mode.
The space allocated by successive calls to LIB$GET_VM_64 may be noncontiguous because another routine can call LIB$GET_VM_64 between your calls. If AST interrupts occur, LIB$GET_VM_64 may allocate space to another routine between execution of any two statements in your program. Even if successive calls to LIB$GET_VM_64 return two contiguous blocks, you must not combine them into one large block that is freed by a single call to LIB$FREE_VM_64.
LIB$GET_VM_64 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_64 routine, then you must have an appropriate action routine for the get operation. That is, in your call to LIB$CREATE_USER_VM_ZONE_64, 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_64 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.

LIB$GET_VM_PAGE

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

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

Description

LIB$GET_VM_PAGE allocates blocks of contiguous (512 byte) pages on VAX systems and pagelets on Alpha 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.

LIB$GET_VM_PAGE_64 (Alpha Only)

The Get Virtual Memory Page routine allocates a specified number of contiguous Alpha 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 pagelets. The number-of-pages argument is the address of a quadword integer that specifies the number of contiguous Alpha 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 pagelets.

Description

LIB$GET_VM_PAGE_64 allocates blocks of contiguous Alpha 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.

LIB$ICHAR

The Convert First Character of String to Integer routine converts the first character of a source string to an 8-bit ASCII integer extended to a longword.

Format

LIB$ICHAR source-string

RETURNS

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by value

First character of the source string. This character is returned by LIB$ICHAR as an 8-bit ASCII value extended to a longword. If the source string has zero length, LIB$ICHAR returns a zero.

Argument

source-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Source string whose first character is converted to an integer by LIB$ICHAR. The source-string argument is the address of a descriptor pointing to this source string.

Description

Although Fortran users can call LIB$ICHAR, it is more efficient to use the Fortran intrinsic function ICHAR, which generates equivalent code in line.

Condition Values Returned

None.

Example


PROGRAM ICHAR(INPUT, OUTPUT); {+} { This program demonstrates how to call LIB$ICHAR { to convert the first character of string to an { integer value. {-} FUNCTION LIB$ICHAR(SRCSTR : VARYING [A] OF CHAR) : INTEGER; EXTERN; {+} { Declare the variables to be used. {-} VAR CHARSTR : VARYING [256] OF CHAR; RET_STATUS : INTEGER; {+} { Begin the main program. Read the character string, { call LIBN$ICHAR, and print the result. {-} BEGIN WRITELN('Enter string: '); READLN(CHARSTR); RET_STATUS := LIB$ICHAR(CHARSTR); WRITELN(RET_STATUS); END.

PROGRAM ICHAR(INPUT, OUTPUT); 
 
{+} 
{ This program demonstrates how to call LIB$ICHAR 
{ to convert the first character of  string to an 
{ integer value. 
{-} 
 
FUNCTION LIB$ICHAR(SRCSTR : VARYING [A] OF CHAR) : INTEGER; 
         EXTERN; 
 
{+} 
{  Declare the variables to be used. 
{-} 
 
VAR 
  CHARSTR       : VARYING [256] OF CHAR; 
  RET_STATUS    : INTEGER; 
 
{+} 
{ Begin the main program.  Read the character string, 
{ call LIBN$ICHAR, and print the result. 
{-} 
 
BEGIN 
  WRITELN('Enter string: '); 
  READLN(CHARSTR); 
  RET_STATUS := LIB$ICHAR(CHARSTR); 
  WRITELN(RET_STATUS); 
END.

The output generated by this Pascal program is as follows:
$ RUN ICHAR Enter string: Pencil sharpener 80 $ RUN ICHAR Enter string: pencil sharpener 112
Notice that this routine changes any uppercase characters to lowercase.

LIB$INDEX

The Index to Relative Position of Substring routine returns an index, which is the relative position of the first occurrence of a substring in the source string.

Format

LIB$INDEX source-string ,sub-string

RETURNS

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by value

The relative position of the first character of the substring if found, or zero if not found.

On Alpha systems, if the relative position of the substring can exceed 2³² - 1, assign the return value to a quadword to ensure that you retrieve the correct relative position.

Arguments

source-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Source string to be searched by LIB$INDEX. The source-string argument is the address of a descriptor pointing to this source string.
sub-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Substring to be found. The sub-string argument is the address of a descriptor pointing to this substring.

Description

The relative character positions returned by LIB$INDEX are numbered 1, 2, ..., n. Zero means that the substring was not found.
If the substring has a zero length, LIB$INDEX returns the value 1, indicating success, no matter how long the source string is. If the source string has a zero length and the substring has a nonzero length, zero is returned, indicating that the substring was not found.
Fortran users may use the built-in INDEX function rather than calling LIB$INDEX directly.

Condition Values Returned

None.

LIB$INIT_DATE_TIME_CONTEXT

The Initialize the Context Area Used in Formatting Dates and Times for Input or Output routine allows the user to initialize the context area used by LIB$FORMAT_DATE_TIME or LIB$CONVERT_DATE_STRING with specific strings, instead of through logical name translation.

Format

LIB$INIT_DATE_TIME_CONTEXT user-context ,component ,init-string

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

user-context

OpenVMS usage: context

type: longword (unsigned)

access: modify

mechanism: by reference

User context 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.
component

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

The component of the context that is being initialized. The component argument is the address of a signed longword that indicates this component. Only one component can be initialized per call to LIB$INIT_DATE_TIME; these component codes are shown in the following list.

LIB$K_MONTH_NAME
LIB$K_MONTH_NAME_ABB
LIB$K_FORMAT_MNEMONICS
LIB$K_WEEKDAY_NAME
LIB$K_WEEKDAY_NAME_ABB
LIB$K_RELATIVE_DAY_NAME

LIB$K_MERIDIEM_INDICATOR
LIB$K_OUTPUT_FORMAT
LIB$K_INPUT_FORMAT
LIB$K_LANGUAGE

init-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

The characters that are to be used in formatting dates and times for input or output. The init-string argument is the address of a descriptor pointing to this string.

Description

The LIB$INIT_DATE_TIME_CONTEXT routine allows the user to initialize the context area used by either LIB$CONVERT_DATE_STRING or LIB$FORMAT_DATE_TIME with specific strings instead of through logical name translations. This routine is therefore useful when the application is formatting either input or output strings that are used only by other computer applications and are not intended for presentation to users.
When the text will be parsed by another program, you must specify all of the context (including spellings). For applications where the context specifies a user's preferred format style, spellings can be looked up from the logical name tables.
Therefore, when the text will be parsed by another program, the minimum effort required to initialize the necessary format strings would be a call to LIB$INIT_DATE_TIME_CONTEXT specifying the input or output format strings to be used. If the specified format requires spelled items, such as month names or day names, then additional calls to LIB$INIT_DATE_TIME_CONTEXT are required to provide the spellings of these items. Applications where the context specifies a user's preferred format style can specify only the language name, and allow the strings to be looked up from logical name tables.
The format of the strings used by this routine is as follows:

[delim][string-1][delim] [string-2][delim]... [delim][string-n][delim]

In this format, [delim] is any character that is not in any of the strings, and [string-x] is the spelling of that instance of the component.
For example, a string passed to this routine to specify the English spellings of the month names might be as follows:
|JAN|FEB|MAR|APR|MAY|JUN |JUL|AUG|SEP|OCT|NOV|DEC|
Note that the string starts and ends with a delimiter. Thus, there is one more delimiter than there are string elements. Each type of component has a natural number of elements associated. The string must contain exactly that number of elements.

Month names (full or abbreviated) 12

Format mnemonics 9

Day names (full or abbreviated) 7

Relative day names 3

Meridiem indicators 2

Output format strings 2

Input format string 1

Language 1

In order to specify the input format mnemonics using LIB$INIT_DATE_TIME_CONTEXT, the user must initialize the component LIB$K_FORMAT_MNEMONICS with the appropriate values. The following table lists in order the 9 fields that must be initialized, along with their default (English) values.

Order Format Field Legible Mnemonic (Defaults)

1 Year YYYY

2 Numeric month MM

3 Numeric day DD

4 Hours (12- or 24-hour) HH

5 Minutes MM

6 Seconds SS

7 Fractional seconds CC

8 Meridiem indicator AM/PM

9 Alphabetic month MONTH

For example, the following would be a valid definition of LIB$K_FORMAT_MNEMONICS using Austrian as the natural language:
|JJJJ|MM|TT|SS|MM|SS|HH| |MONAT|
To specify an output format using LIB$INIT_DATE_TIME_CONTEXT, the user must initialize the variable LIB$K_OUTPUT_FORMAT. There are two elements associated with this output format string. One describes the date format fields, the other the time format fields. The order in which they appear in the string determines the order in which they are output. A single space is inserted into the output stream between the two elements, if the call to LIB$FORMAT_DATE_TIME specifies that both be output. In the following example, the two elements associated with the output format string are delimited by vertical bars.
|!DB-!MAAU-!Y4|!H04:!M0:!S0.!C2|
This output format string represents the format used by the $ASCTIM system service for outputting times. Note that the middle delimiter is replaced by a space in the resultant output.
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.

Order	Format Field	Legible Mnemonic (Defaults)
1	Year	YYYY
2	Numeric month	MM
3	Numeric day	DD
4	Hours (12- or 24-hour)	HH
5	Minutes	MM
6	Seconds	SS
7	Fractional seconds	CC
8	Meridiem indicator	AM/PM
9	Alphabetic month	MONTH

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_ILLCOMPONENT Illegal value for the component.

LIB$_ILLINISTR Illegally formed init-string.

LIB$_NUMELEMENTS Incorrect number of elements for the component.

LIB$_UNRFORCOD Unrecognized format code.

Contents

Index

privacy and legal statement

5932PRO_026.HTML

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

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

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

OpenVMS usage:	identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

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

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

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

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Month names (full or abbreviated)	12
Format mnemonics	9
Day names (full or abbreviated)	7
Relative day names	3
Meridiem indicators	2
Output format strings	2
Input format string	1
Language	1

SS$_NORMAL	Routine successfully completed.
LIB$_ILLCOMPONENT	Illegal value for the component.
LIB$_ILLINISTR	Illegally formed init-string.
LIB$_NUMELEMENTS	Incorrect number of elements for the component.
LIB$_UNRFORCOD	Unrecognized format code.