Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_026.HTML