Document revision date: 19 July 1999

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.

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.

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.

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.

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.

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.

	privacy and legal statement
5933PRO_008.HTML