VA FileMan Programmer Manual: PUT^DDSVAL( )

Contents:

Main

ScreenMan API

PUT^DDSVAL( )

You can use this entry point only within a ScreenMan form, in all places where M code can be placed on the form.

This procedure stuffs data into a data dictionary field as part of ScreenMan's transaction. The data passed to this procedure 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 procedure 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 FLAGS (described below) does not contain an I, the value must be in the form of a valid, unambiguous user response. If FIELD 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. 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 and "LAST" indicates that the subrecord with the highest internal entry number should be displayed.
.ERROR	(Optional) $D(ERROR)>1, if the procedure call fails.
FLAGS	Indicates whether VALUE 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	VALUE is in Internal form; it is not validated.
	E	VALUE is in External form. (Default)
	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: March 10, 2007