HP OpenVMS RTL General Purpose (OTS$) Manual

Contents

Index

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.

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.

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 Strings, Free One Dynamic 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 CHARACTER80 DATA_LINE INTEGER4 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

        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

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

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

	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

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

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

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