![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS RTL General Purpose (OTS$) Manual
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.
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)