HP OpenVMS systems documentation

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.