OLEStrAlloc

f90VB Modules

f90VBDefs, f90VBBStrings

Summary

OLEStrAlloc allocates and initializes a Fortran OLE String. If the passed Fortran OLE String was already initialized, the procedure will destroy its original content, release the memory, and reallocate the necessary space for the new content.

Syntax

Arguments

StrDest [Input/Output]

Destination string. StrDest must be a Fortran OLE String structure.

StrSrc [Input]

String with content used to initialize StrDest. StrSrc can be any of the f90VB string types (Fortran Strings, Fixed OLE Strings, Fortran OLE Strings or BStrings).

iRet [Output, Optional]

Upon return, iRet contains the number of characters copied to StrDest, or BSTRINGS_ERROR if the procedure failed.

StrLen [Input, Optional]

Number of characters from StrSrc that should be copied to StrDest. If StrLen>StrLenTrim(StrSrc), then StrDest's buffer is allocated to the size indicated in StrLen, and all characters in StrSrc are copied to StrDest. If StrLen is not passed, OLEStrAlloc assumes its value is the same as the trimmed length of StrSrc.

Comments

OLEStrAlloc will allocate a new buffer for the destination string if the destination string has not already been allocated by the calling program. If StrDest has been allocated before calling OLEStrAlloc, the procedure might reallocate the string to ensure it can accommodate the characters transferred from StrSrc.

The size of the new buffer depends on the values passed in argument StrLen. If argument StrLen is not passed or has a negative value, the StrDest buffer is allocated to, at least, the size returned by function StrLenTrim(StrSrc). If StrLen is larger than StrLenTrim(StrSrc), the buffer allocated for StrDest is, at least, the size indicated in StrLen.

If OLEStrAlloc is successful, StrDest%Str contains the allocated/initialized string, and StrDest%StrHndl points to the address of StrDest%Str.

If OLEStrAlloc fails, the original content of the destination string may or may not be destroyed, and argument iRet is set to BSTRINGS_ERROR upon return from the procedure. The only case in which StrDest might be destroyed is when OLEStrAlloc fails due to lack of available memory to allocate the new string.

OLEStrAlloc always uses the default code page and conversion flag values when StrSrc is a Fortran String. If you want to create a Fortran OLE String with user-specified code page and flags, you can use the more general procedure StrCopy.

To restore the memory used by StrDest created with OLEStrAlloc, the calling program must explicitly deallocate the string using subroutine StrFree.

Argument StrLen

Argument StrLen is used to indicate how many of the characters in StrSrc should be copied to StrDest. If zero is passed in argument StrLen, OLEStrAlloc allocates StrDest and sets its content to null (an empty string). If argument StrLen is not passed or has a negative value, the StrDest buffer is allocated to, at least, the size of StrLenTrim(StrSrc).

Note: When the size of the largest string to store in a dynamic type is known beforehand, initially allocating StrDest to this size may speed up further assignments.

Examples

!demonstrates use of OLEStrAlloc to create/change

!Fortran OLE String

!Copyright 1999-2000, Canaima Software

!All rights reserved

!load f90VB modules

use f90VBDefs

use f90VBBStrings

implicit none

!declare Fortran OLE String structures

type(OLESTRING)::OLEStrA,OLEStrB

!utility variables

character(len=100)::FStr

integer(HRESULT_KIND)::iRet

integer::i

!create a Fortran OLE String

call OLEStrAlloc(OLEStrA,'This is OLE String A',iRet)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating Fortran OLE String'

else

    call StrCopy(OLEStrA,FStr)

    print *,''

    print *,'Fortran OLE String Created'

    print *,'OLE String Length:',StrLenTrim(OLEStrA)

    print *,'OLE String Buffer length:', StrLen(OLEStrA)

    print *,'OLE String content:',trim(FStr)

    print *,'Fortran OLE String structure:'

    print *,'String handle:',OLEStrA%StrHndl

    print *,'First 5 characters:', (OLEStrA%Str(i),i=1,5)

    print *,'First 5 characters in ascii:',(achar(OLEStrA%Str(i)),i=1,5)

endif

!create a Fortran OLE String, forcing a larger buffer

call OLEStrAlloc(OLEStrB,'This is OLE String B',iRet,50)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating Fortran OLE String'

else

    call StrCopy(OLEStrB,FStr)

    print *,''

    print *,'Fortran OLE String Created'

    print *,'OLE String Length:',StrLenTrim(OLEStrB)

    print *,'OLE String Buffer length:', StrLen(OLEStrB)

    print *,'OLE String content:',trim(FStr)

    print *,'Fortran OLE String structure:'

    print *,'String handle:',OLEStrB%StrHndl

    print *,'First 5 characters:', (OLEStrB%Str(i),i=1,5)

    print *,'First 5 characters in ascii:',(achar(OLEStrB%Str(i)),i=1,5)

endif

!reallocate OLEStrA and copy content from OLEStrB

call OLEStrAlloc(OLEStrA, OLEStrB, iRet)

if (iRet.eq.BSTRINGS_ERROR) then

    print *,'Error creating Fortran OLE String'

else

    call StrCopy(OLEStrA,FStr)

    print *,''

    print *,'Fortran OLE String Created'

    print *,'OLE String Length:',StrLenTrim(OLEStrA)

    print *,'OLE String Buffer length:', StrLen(OLEStrA)

    print *,'OLE String content:',trim(FStr)

    print *,'Fortran OLE String structure:'

    print *,'String handle:',OLEStrA%StrHndl

endif

!Free memory used by Fortran OLE Strings

call StrFree(OLEStrA)

call StrFree(OLEStrB)

stop

end

Related Topics

StrByteLen