OpenVMS RTL Library (LIB$) Manual
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.
|
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
232 - 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.
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.
|
|
