DMcob_ValueGetBuffer

6.8.61 DMcob_ValueGetBuffer

This function allows to retrieve a single element value that belongs to a defined index from collections. Unlike DMcob_ValueGet, this function provides a buffer for string return values that is larger than the standard buffer.

If the given index is of type DT-void, the entire value is returned, which usually means copying the value.

If the DM-Value parameter is an unmanaged value, it remains unmanaged. When strings are returned, they are only stored in a temporary buffer which may be cleared or overwritten the next time a DM function without the DMF-DontFreeLastStrings option is called.

77 AnyValue pointer value  null.
77 StringBuffer pic X(100) value  spaces.
77 StringLength pic 9(9)   binary value 100.

call "DMcob_ValueGetBuffer" using
            DM-StdArgs
            AnyValue
            DM-ValueIndex
            DM-Value
            StringBuffer
            StringLength.

Parameters

<-> DM-options of DM-StdArgs

These are the options available:

Option	Meaning
DMF-GetLocalString	This option means that text values (IDs of type DT-text) should be returned as strings in the currently set language.
DMF-GetMasterString	This option means that text values (IDs of type DT-text) should be returned as a strings in the development language, regardless of which language the user is currently working with.
DMF-DontFreeLastStrings	Strings are usually passed to the application in a temporary buffer, which is retained until the next call to the IDM. If strings in the application shall be valid longer, the option DMF-DontFreeLastStrings has to be set. Then the memory will not be released until an IDM function returning a string from the IDM to the applicationis called without this option.

-> AnyValue

Handle of the Managed Value. It should be a managed value reference or function argument.

-> DM-ValueIndex

This parameter sets the index for which the element value is retrieved. This parameter does not need to be a managed value. If DM-idx-datatype is set to the value DT-void, then the DM-Value parameter is returned.

<- DM-Value

This parameter defines the value to be set. It may be a managed or an unmanaged value reference.

<- StringBuffer

Buffer for the string, to obtain strings longer than 80 characters.

-> StringLength

Length of the buffer (100 here), must match the definition.

Return value

DM-status of DM-StdArgs

DM-error	The value could not be retrieved. This may be due to an faulty call, an unmanaged or invalid value reference, or an incorrect indexing.
DM-success	Getting the value has been successful.

Availability

COBOL Interface for Micro Focus Visual COBOL only.