VA FileMan Programmer Manual: HELP^DIE( )

Contents:

Main

Database Server (DBS) API

HELP^DIE(): Helper

Reference Type	Category	ICR #
Supported	Database Server (DBS)	2053

Description

The HELP^DIE API (aka Helper) retrieves user-oriented help for a field from the data dictionary (DD) and other sources. The help is returned in arrays. Use the MSG^DIALOG API to display the help.

You control the kind of help obtained by using the flags input parameter:

Specific kind of help.
Help normally returned with one or two question marks.
All available help for a field.

Format

HELP^DIE(file[,iens],field,flags[,msg_root])

Input Parameters

FILE	(Required) File or subfile number.
IENS	(Optional) Standard IENS indicating internal entry numbers. This parameter is only needed if code in the data dictionary for Executable Help or Screen on a SET OF CODES references the entry number using DA() array or D0, D1, etc., and if that kind of help is being requested.
FIELD	(Required) Field number for which help is requested.
FLAGS	(Required) Flags used to determine what kind of help is returned by the call. If a lowercase letter is shown, use it to suppress that kind of help; useful in conjunction with ? or ??. The possible values are:
	?	Help equivalent to user entering one ? at an edit prompt. Also, help returned for an invalid response.
	??	Help equivalent to user entering ?? at an edit prompt.
	A	All available help for the field.
	B (b)	Brief VARIABLE POINTER help. A single line beginning with "To see the entries ...". REF: See also "Limitations" under the "Details and Features" section.
	C	Set of Codes screen description.
	D	Description text for the field; this can be multiple lines.
	F	Fields that can be used for lookups. Returned for top-level .01 fields and for pointed-to files for a DATA TYPE field value of POINTER data. For pointed-to files, the F flag is effective only if the G flag is also sent.
	G (g)	Getting help from pointed-to file. Help for the .01 field of pointed-to file is returned.
	H	Help prompt text.
	M	More VARIABLE POINTER help. Detailed description of how to enter VARIABLE POINTER data.
	P	Pointer screen description.
	S	SET OF CODES possible choices. Any screen that exists on the SET OF CODES field is applied so that only actually selectable choices are presented.
	T	Date/Time generic help. This help text is customized based on the allowable and required elements of the DATE/TIME field.
	U	Unscreened SET OF CODES choices.
	V	VARIABLE POINTER help that lists the prefixes and messages associated with a particular VARIABLE POINTER field.
	X	EXecutable help-the M code contained in executable help is executed. To have the help returned in an array, the executed code must use EN^DDIOL to load the help message.
msg_root	(Optional) Closed root into which the output from the call is put. If not supplied, output is returned in ^TMP (see Output).

Output

The default output from this call is:

DIHELP	Number of lines of help text returned
^TMP("DIHELP",$J,n)	Array containing the lines of help text. The text is found in integer subscripted nodes (n), beginning with 1. A blank node is inserted between each different type of help returned.

If error messages are necessary, they are returned in the standard manner.

If the msg_root is included in the input parameters, output is returned there instead of ^TMP. The help text is returned in nodes descendent from MSG_ROOT("DIHELP").

Example

Figure 170 illustrates the use of this call to return help text from a field that has a DATA TYPE field value of SET OF CODES. This is the same help that can be obtained with a ? in a traditional VA FileMan call.

NOTE: The help is returned in the specified array descendent from MYHELP(1).

Figure 170: HELP^DIE API—Example: Input and Output

    >D HELP^DIE(16200,"",5,"?","MYHELP(1)") <Enter>

    >ZW MYHELP <Enter>
    MYHELP(1,"DIHELP")=5
    MYHELP(1,"DIHELP",1)=Only YES and MAYBE are acceptable.
    MYHELP(1,"DIHELP",2)=
    MYHELP(1,"DIHELP",3)=Choose from:
    MYHELP(1,"DIHELP",4)=Y        YES
    MYHELP(1,"DIHELP",5)=M        MAYBE

Error Codes Returned

Table 55 lists the possible error codes returned with the HELP^DIE API:

Table 55: HELP^DIE API—Error Codes Returned

Code	Description
120	Error occurred during execution of a FileMan hook.
301	An invalid flag was passed.
501	Field does not exist.

Details and Features

Helper and Validator

Based on a flag passed to the Validator call, single question mark help is returned by the Validator if the value being checked is invalid.

Pointed-to Files

By default, you receive help for the .01 field of pointed-to files with ? or ?? when the field on which you are requesting help is a POINTER. If you do not want this extended help returned, use the (lowercase) g flag.

Limitations

This call does not return lists of entries for .01, POINTER, or VARIABLE POINTER fields. Use the Lister utility to obtain these lists.

The (lowercase) b flag suppresses the line of VARIABLE POINTER help that indicates a user can get a list of entries if they type <Prefix.?>. Use this flag with ? if you are not supporting this capability.

Reviewed/Updated: May 2026