VA FileMan Programmer Manual: PUT^DDSVAL( )

Contents:

Main

ScreenMan API

PUT^DDSVAL(): Stuff Data into a DATA DICTIONARY Field

Reference Type	Category	ICR #
Supported	ScreenMan	10149

You can use the PUT^DDSVAL API only within a ScreenMan form, in all places where M code can be placed on the form.

The PUT^DDSVAL API stuffs data into a DATA DICTIONARY field as part of ScreenMan's transaction. The data passed to this API is filed in the database only when the user explicitly saves changes. Until then, it is stored in a temporary location.

If the specified field is a WORD-PROCESSING field, the value passed to the API is the closed root of the array that contains the text.

If the specified field is a Multiple field, the value passed is the subrecord first displayed to the user as a default at the Multiple field. This value is a default for selection and is not actually filed.

Values cannot be stuffed into COMPUTED fields.

If, while a form is running, a call to PUT^DDSVAL fails, ScreenMan prints an error message in the Command Area.

Format

PUT^DDSVAL(file,[.]record,field,value[,.error][,flags])

Input Parameters

file	(Required) The global root or number of the file or subfile. At the field level, the local variable DIE contains the current global root.
[.]record	(Required) The internal entry number or an array of internal entry numbers. This parameter has the same form as the DA array. At the field level, the local array DA contains the current array of record numbers.
field	(Required) The field name or number.
value	(Required) The value to stuff into the DATA DICTIONARY field. If the flags parameter does not contain an I, the value must be in the form of a valid, unambiguous user response. If the field parameter is a WORD-PROCESSING field, value must be the closed root of the array that contains the text. The subscripts of the nodes below the root must be positive numbers, although they need not be integers, and there can be gaps in the sequence. The text must be in these nodes or in the 0 node descendent from these nodes. If field is a Multiple field, value determines the subrecord to display to the user as a default for selection. It is not a value that is ever filed. The value can be "FIRST", "LAST", or the specific internal entry number of the subrecord to display: "FIRST" indicates that the subrecord with the lowest internal entry number should be displayed. "LAST" indicates that the subrecord with the highest internal entry number should be displayed.
.error	(Optional) $D(ERROR)>1, if the API call fails.
flags	(Optional) Indicates whether the value parameter is in internal or external form, as shown below:
	A	Append new word-processing text to the current text. This flag can be used only when stuffing text into a WORD-PROCESSING field. If the A flag is not sent, the current word-processing text is completely erased before the new text is added.
	I	The value parameter is in Internal form; it is not validated.
	E (Default)	The value parameter is in External form.
	The I and E flags have no effect when field is a WORD-PROCESSING field.

Examples

Example 1

Stuff the value 2940801 into a date Field #20. The value passed is in internal form:

    D PUT^DDSVAL(DIE,.DA,20,2940801,"","I")

No data validation is performed.

Example 2

Stuff word-processing text from an array into a WORD-PROCESSING field named DESCRIPTION as shown below:

    D PUT^DDSVAL(DIE,.DA,"DESCRIPTION","^nmspWP(""TEXT"")")

The array that contains the text looks like:

    ^nmspWP("TEXT",1,0)=Line 1
    ^nmspWP("TEXT",2,0)=Line 2
        ...etc.

OR:

    ^nmspWP("TEXT",1)=Line 1
    ^nmspWP("TEXT",2)=Line 2
        ...etc.

Reviewed/Updated: May 2026