Document revision date: 30 March 2001

## OpenVMS RTL General Purpose (OTS$) Manual

Previous | Contents | Index

## OTS$POWxLU

> The Raise a Floating-Point Base to an Unsigned Longword Integer Exponent routines raise a floating-point base to an unsigned longword integer exponent.

### Format

> OTS$POWRLU floating-point-base ,unsigned-lword-int-exponent

> OTS$POWDLU floating-point-base ,unsigned-lword-int-exponent

> OTS$POWGLU floating-point-base ,unsigned-lword-int-exponent

> OTS$POWHLU_R3 floating-point-base ,unsigned-lword-int-exponent (VAX only)

### RETURNS

> OpenVMS usage: | floating_point
> type: | F_floating, D_floating, G_floating, H_floating
> access: | write only
> mechanism: | by value

> Result of raising a floating-point base to an unsigned longword integer exponent. OTS$POWRLU returns an F-floating number. OTS$POWDLU returns a D-floating number. OTS$POWGLU returns a G-floating number.

> On VAX systems, OTS$POWHLU_R3 returns an H-floating number.

### Arguments

> #### floating-point-base

> OpenVMS usage: | floating_point
> type: | F_floating, D_floating, G_floating, H_floating
> access: | read only
> mechanism: | by value

> Floating-point base. The floating-point-base argument contains the value of the base. For OTS$POWRLU, floating-point-base is an F-floating number. For OTS$POWDLU, floating-point-base is a D-floating number. For OTS$POWGLU, floating-point-base is a G-floating number. For OTS$POWHLU_R3, floating-point-base is an H-floating number.

> #### unsigned-lword-int-exponent

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Integer exponent. The unsigned-lword-int-exponent argument contains the value of the unsigned longword integer exponent.

### Description

> OTS$POWRLU, OTS$POWDLU, OTS$POWGLU, and OTS$POWHLU_R3 return the result of raising a floating-point base to an unsigned longword integer exponent. The floating-point result is as follows:

> Base | Exponent | Result
> --- | --- | ---
> Any | > 0 | Product of ( base*2 i ), where i is each nonzero bit position in longword-integer-exponent.
> > 0 | = 0 | 1.0
> = 0 | = 0 | Undefined exponentiation.
> < 0 | = 0 | 1.0

> On Alpha systems, some restrictions apply when linking OTS$POWRLU or OTS$POWGLU. See Chapter 1 for more information about these restrictions.

### Condition Values Signaled

> MTH$_FLOOVEMAT | Floating-point overflow in math library.
> MTH$_FLOUNDMAT | Floating-point underflow in math library. This can only occur if the caller has floating-point underflow enabled.
> MTH$_UNDEXP | Undefined exponentiation. This occurs if both the floating-point-base and unsigned-longword-integer-exponent arguments are zero.

## OTS$SCOPY_DXDX

> The Copy a Source String Passed by Descriptor to a Destination String routine copies a source string to a destination string. Both strings are passed by descriptor.

### Format

> OTS$SCOPY_DXDX source-string ,destination-string

> ### Corresponding JSB Entry Point

> OTS$SCOPY_DXDX6

### RETURNS

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by value

> Number of bytes not moved to the destination string if the length of source-string is greater than the length of destination-string. The value is 0 (zero) otherwise.

### Arguments

> #### source-string

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

> Source string. The source-string argument is the address of a descriptor pointing to the source string. The descriptor class can be unspecified, fixed length, dynamic, scalar decimal, array, noncontiguous array, or varying.

> #### destination-string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Destination string. The destination-string argument is the address of a descriptor pointing to the destination string. The class field determines the appropriate action.

> See the Description section for further information.

### Description

> OTS$SCOPY_DXDX copies a source string to a destination string. It passes the source string by descriptor. If the length of the source string is greater than the length of the destination string, OTS$SCOPY_DXDX returns the number of bytes not moved to the destination string. If the length of the source string is less than or equal to the length of the destination string, it returns 0 (zero). All error conditions except truncation are signaled; truncation is ignored.

> An equivalent JSB entry point is provided, with R0 being the first argument (the descriptor of the source string), and R1 the second (the descriptor of the destination string). On return, R0 through R5 and the PSL are as they would be after a VAX MOVC5 instruction. R0 through R5 contain the following:

> | R0 | Number of bytes of source string not moved to destination string
> | R1 | Address one byte beyond the last copied byte in the source string
> | R2 | 0
> | R3 | Address one byte beyond the destination string
> | R4 | 0
> | R5 | 0

> For further information, see the VAX Architecture Reference Manual.

> The actions taken by OTS$SCOPY_DXDX depend on the descriptor class of the destination string. The following table describes these actions for each descriptor class:

> Descriptor Class | Action
> --- | ---
> S, Z, SD, A, NCA | Copy the source string. If needed, space fill or truncate on the right.
> D | If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor.
> | If the area specified is not large enough, return the previous space allocation if any, and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor.
> VS | Copy source string to destination string up to the limit of the destination descriptor's MAXSTRLEN field with no padding. Adjust the string's current length field (CURLEN) to the actual number of bytes copied.

### Condition Values Signaled

> OTS$_FATINTERR | Fatal internal error.
> OTS$_INVSTRDES | Invalid string descriptor.
> OTS$_INSVIRMEM | Insufficient virtual memory.

## OTS$SCOPY_R_DX

> The Copy a Source String Passed by Reference to a Destination String routine copies a source string passed by reference to a destination string.

### Format

> OTS$SCOPY_R_DX word-int-source-length-val ,source-string-address ,destination-string

> ### Corresponding JSB Entry Point

> OTS$SCOPY_R_DX6

### RETURNS

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | write only
> mechanism: | by value

> Number of bytes not moved to the destination string if the length of the source string pointed to by source-string-address is greater than the length of destination-string. Otherwise, the value is 0 (zero).

### Arguments

> #### word-int-source-length-val

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | read only
> mechanism: | by value

> Length of the source string. The word-int-source-length-val argument is an unsigned word integer containing the length of the source string.

> #### source-string-address

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by reference

> Source string. The source-string-address argument is the address of the source string.

> #### destination-string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Destination string. The destination-string argument is the address of a descriptor pointing to the destination string. OTS$SCOPY_R_DX determines the appropriate action based on the descriptor's CLASS field. The descriptor's LENGTH field alone or both the POINTER and LENGTH fields can be modified if the string is dynamic. For varying strings, the string's current length (CURLEN) is rewritten.

### Description

> OTS$SCOPY_R_DX copies a source string to a destination string. It passes the source string by reference preceded by a length argument. The length argument, word-int-source-length-val, is passed by value.

> If the length of the source string is greater than the length of the destination string, OTS$SCOPY_R_DX returns the number of bytes not moved to the destination string. If the length of the source string is less than or equal to the length of the destination string, it returns 0 (zero). All conditions except truncation are signaled; truncation is ignored.

> An equivalent JSB entry point is provided, with R0 being the first argument, R1 the second, and R2 the third, if any. The length argument is passed in bits 15:0 of the appropriate register. On return, R0 through R5 and the PSL are as they would be after a VAX MOVC5 instruction. R0 through R5 contain the following:

> | R0 | Number of bytes of source string not moved to destination string
> | R1 | Address one byte beyond the last copied byte in the source string
> | R2 | 0
> | R3 | Address one byte beyond the destination string
> | R4 | 0
> | R5 | 0

> For additional information, see the VAX Architecture Reference Manual.

> The actions taken by OTS$SCOPY_R_DX depend on the descriptor class of the destination string. The following table describes these actions for each descriptor class:

> Descriptor Class | Action
> --- | ---
> S, Z, SD, A, NCA | Copy the source string. If needed, space fill or truncate on the right.
> D | If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor.
> | If the area specified is not large enough, return the previous space allocation (if any) and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor.
> VS | Copy source string to destination string up to the limit of the descriptor's MAXSTRLEN field with no padding. Adjust the string's current length (CURLEN) field to the actual number of bytes copied.

### Condition Values Signaled

> OTS$_FATINTERR | Fatal internal error.
> OTS$_INVSTRDES | Invalid string descriptor.
> OTS$_INSVIRMEM | Insufficient virtual memory.

### Example

> A Fortran example that demonstrates the manipulation of dynamic strings appears at the end of OTS$SGET1_DD. This example uses OTS$SCOPY_R_DX, OTS$SGET1_DD, and OTS$SFREE1_DD.

## OTS$SFREE1_DD

> The Free One Dynamic String routine returns one dynamic string area to free storage.

### Format

> OTS$SFREE1_DD dynamic-descriptor

> ### Corresponding JSB Entry Point

> OTS$SFREE1_DD6

### RETURNS

> None.

### Argument

> #### dynamic-descriptor

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | modify
> mechanism: | by reference

> Dynamic string descriptor. The dynamic-descriptor argument is the address of the dynamic string descriptor. The descriptor is assumed to be dynamic and its class field is not checked.

### Description

> OTS$SFREE1_DD deallocates the described string space and flags the descriptor as describing no string at all. The descriptor's POINTER and LENGTH fields contain 0.

### Condition Value Signaled

> OTS$_FATINTERR | Fatal internal error.

### Example

> A Fortran example that demonstrates the manipulation of dynamic strings appears at the end of OTS$SGET1_DD. This example uses OTS$SFREE1_DD, OTS$SGET1_DD, and OTS$SCOPY_R_DX.

## OTS$SFREEN_DD

> The Free n Dynamic Strings routine takes as input a vector of one or more dynamic string areas and returns them to free storage.

### Format

> OTS$SFREEN_DD descriptor-count-value ,first-descriptor

> ### Corresponding JSB Entry Point

> OTS$SFREEN_DD6

### RETURNS

> None.

### Arguments

> #### descriptor-count-value

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Number of adjacent descriptors to be flagged as having no allocated area (the descriptor's POINTER and LENGTH fields contain 0) and to have their allocated areas returned to free storage by OTS$SFREEN_DD. The descriptor-count-value argument is an unsigned longword containing this number.

> #### first-descriptor

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | modify
> mechanism: | by reference

> First string descriptor of an array of string descriptors. The first-descriptor argument is the address of the first string descriptor. The descriptors are assumed to be dynamic, and their class fields are not checked.

### Description

> OTS$SFREEN_DD6 deallocates the described string space and flags each descriptor as describing no string at all. The descriptor's POINTER and LENGTH fields contain 0.

### Condition Values Signaled

> OTS$_FATINTERR | Fatal internal error.

## OTS$SGET1_DD

> The Get One Dynamic String routine allocates a specified number of bytes of dynamic virtual memory to a specified string descriptor.

### Format

> OTS$SGET1_DD word-integer-length-value ,dynamic-descriptor

> ### Corresponding JSB Entry Point

> OTS$SGET1_DD_R6

### RETURNS

> None.

### Arguments

> #### word-integer-length-value

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | read only
> mechanism: | by value

> Number of bytes to be allocated. The word-integer-length-value argument contains the number of bytes. The amount of storage allocated is automatically rounded up. If the number of bytes is zero, a small number of bytes is allocated.

> #### dynamic-descriptor

> OpenVMS usage: | quadword_unsigned
> type: | quadword (unsigned)
> access: | modify
> mechanism: | by reference

> Dynamic string descriptor to which the area is to be allocated. The dyn-str argument is the address of the dynamic string descriptor. The CLASS field is not checked but it is set to dynamic (CLASS = 2). The LENGTH field is set to word-integer-length-value and the POINTER field is set to the string area allocated (first byte beyond the header).

### Description

> OTS$SGET1_DD allocates a specified number of bytes of dynamic virtual memory to a specified string descriptor. This routine is identical to OTS$SCOPY_DXDX except that no source string is copied. You can write anything you want in the allocated area.

> If the specified string descriptor already has dynamic memory allocated to it, but the amount allocated is either greater than or less than word-integer-length-value, that space is deallocated before OTS$SGET1_DD allocates new space.

### Condition Values Signaled

> OTS$_FATINTERR | Fatal internal error.
> OTS$_INSVIRMEM | Insufficient virtual memory.

### Example

            PROGRAM STRING_TEST

    C+
    C       This program demonstrates the use of some dynamic string
    C       manipulation routines.
    C-

    C+
    C       DECLARATIONS
    C-

            IMPLICIT NONE
            CHARACTER*80    DATA_LINE
            INTEGER*4       DATA_LEN, DSC(2), CRLF_DSC(2), TEMP_DSC(2)
            CHARACTER*2     CRLF

    C+
    C       Initialize the output descriptor.  It should be empty.
    C-

            CALL OTS$SGET1_DD(%VAL(0), DSC)

    C+
    C       Initialize a descriptor to the string CRLF and copy the
    C       character CRLF to it.
    C-

            CALL OTS$SGET1_DD(%VAL(2), CRLF_DSC)
            CRLF = CHAR(13)//CHAR(10)
            CALL OTS$SCOPY_R_DX( %VAL(2), %REF(CRLF(1:1)), CRLF_DSC)

    C+
    C       Initialize a temporary descriptor.
    C-

            CALL OTS$SGET1_DD(%VAL(0), TEMP_DSC)

    C+
    C       Prompt the user.
    C-

            WRITE(6, 999)
    999     FORMAT(1X, 'Enter your message, end with Ctrl/Z.')

    C+
    C       Read lines of text from the terminal until end-of-file.
    C       Concatenate each line to the previous input.  Include a
    C       CRLF between each line.
    C-

            DO WHILE (.TRUE.)
                READ(5, 998, ERR = 10) DATA_LEN, DATA_LINE
    998         FORMAT(Q,A)
                CALL OTS$SCOPY_R_DX( %VAL(DATA_LEN),
         1         %REF(DATA_LINE(1:1)),
         2         TEMP_DSC)
                CALL STR$CONCAT( DSC, DSC, TEMP_DSC, CRLF_DSC )
            END DO

    C+
    C       The user has typed Ctrl/Z.  Output the data we read.
    C-

    10      CALL LIB$PUT_OUTPUT( DSC )
    C+
    C       Free the storage allocated to the dynamic strings.
    C-

            CALL OTS$SFREE1_DD( DSC )
            CALL OTS$SFREE1_DD( CRLF_DSC )
            CALL OTS$SFREE1_DD( TEMP_DSC )

    C+
    C       End of program.
    C-

            STOP
            END

> This Fortran example program demonstrates the manipulation of dynamic strings using OTS$SGET1_DD, OTS$SFREE1_DD, and OTS$SCOPY_R_DX.

Index | Contents

| privacy and legal statement |
5933PRO_008.HTML