VA FileMan V. 22.0 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API


HELP^DIE( ): Helper

This procedure retrieves user-oriented help for a field from the Data Dictionary and other sources. The help is returned in arrays. (The MSG^DIALOG procedure can be used to display the help.) You control the kind of help obtained by using the FLAGS input parameter - either a specific kind of help, the help normally returned with one or two question marks, or 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 Xecutable 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 lower case 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 ...".
NOTE: See also "Limitations" under "Details and Features " below.

C

Set of Codes screen description.

D

Description text for the field; this may be multiple lines.

F

Fields that can be used for lookups. Returned for top-level .01 fields and for pointed-to files for pointer data types. 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 particular 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

Xecutable help-the M code contained in Xecutable Help is executed. In order 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

The following example illustrates the use of this call to return help text from a field that is a Set of Codes data type. This is the same help that can be obtained with a "?" in a traditional FileMan call. Note that the help is returned in the specified array descendent from MYHELP(1):

    >D HELP^DIE(16200,"",5,"?","MYHELP(1)")
    
    >ZW MYHELP
    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
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 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 b flag will suppress 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: March 10, 2007