Retrieve field information

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall DD_FIELD(dcs, DDF_LIST, names_req, array, [start][, #names])


xcall DD_FIELD(dcs, DDF_SLIST, names_req, array, [start][, #names])


xcall DD_FIELD(dcs, DDF_INFO, name, f_info)


xcall DD_FIELD(dcs, DDF_TEXT, field, data)


xcall DD_FIELD(dcs, DDF_GROUP, name)




The repository control structure.


Returns the current structure’s field names in alphabetical order.


The number of field names requested. (d3)


Returned with the array of field names. ((*)a30)


(optional) Contains the field name at which to start. (a30)


(optional) Returned with the number of field names. (d3)


Returns the current structure’s field names in sequence order.


Returns general field information and sets the current field.


The unique field name. (a30)


Returned with the field data. See the f_info record definition in the ddinfo.def file.


Returns textual information about the current field.


A field in the f_info record that indicates what type of textual information should be returned in data (if the field is non‑zero):

fi_struct = Referenced structure for implicit group. (a30)

fi_prefix = Group member prefix. (a30)

fi_desc = Short description. (a40)

fi_ldesc = Long description. (a1800)

fi_usrtyp = User data type string. (a30)

fi_enmfld = Enumeration name for Enum field. (a30)

fi_strfld = Structure (or alias) name for Struct field. (a3 0)

fi_heading = Column heading. (a40)

fi_prompt = Prompt text. (a80)

fi_help = Help identifier. (a80)

fi_infoln = Information string. (a80)

fi_utext = User text string. (a80)

fi_altnm = Alternate field name. (a30)

fi_font = Font. (a30)

fi_prmptfont = Prompt font. (a30)

fi_def = Default value. (a80)

fi_alwlst = Allow list entries. (See fti_entlst in ddinfo.def.)

fi_range = Range values. (See fti_range in ddinfo.def.)

fi_enum = Enumerated field data. (See fti_enum in ddinfo.def.)

fi_sellist = Selection list entries. (See fti_entlst in ddinfo.def.)

fi_arrivemeth = Arrive method. (a30)

fi_leavemeth = Leave method. (a30)

fi_drillmeth = Drill method. (a30)

fi_hypermeth = Hyperlink method. (a30)

fi_changemeth = Change method. (a30)

fi_dispmeth = Display method. (a30)

fi_editfmtmeth = Edit format method. (a30)


Returned with the requested textual data.


Sets field context to the first member of the group name.


Sets field context back to the group member’s parent field.

The DD_FIELD subroutine returns information about fields for the current structure. There are six ways to call DD_FIELD:

You must have previously set the current structure with the DD_STRUCT subroutine. The same DD_STRUCT call should also have told you the number of fields that exist.


If you pass DDF_LIST or DDF_SLIST, the DD_FIELD subroutine returns an array of field names for the current structure. If you pass DDF_LIST, the names are returned in alphabetical order, starting with either the first name found or the specified name. If you pass DDF_SLIST, the names are returned in sequence order (the order defined within the structure), starting with either the first name defined or the specified name.

DD_FIELD returns as many field names as are found or as are requested, whichever is smaller. The actual number of names in the array can be returned in #names. You must make sure that the buffer passed is large enough to hold the number of names that you are requesting.

To obtain a list of fields for an alias structure, use the DD_ALIAS subroutine.

When you pass DDF_LIST or DDF_SLIST, the DD_FIELD subroutine returns field names from the structure level only. To access the fields that are members of a group, you must first use DDF_INFO on each field and test the group flag (fi_group). If the group flag is set, then the field is a group. You must next determine if it is an explicit group or an implicit group (fi_struct is non‑blank for implicit groups).

If the field is an explicit group, you must use DDF_GROUP to establish context for that group, and then use DDF_LIST or DDF_SLIST to access its members. This logic must be programmed in a recursive manner, as there is no limit to the number of nested groups.

If the field is an implicit group, you must copy the data from the current dcs into another control structure, and then pass it and fi_struct to the DD_STRUCT subroutine to establish context for obtaining the implicit group members. You would then use DD_FIELD to access its members, just as you did for the original structure. Remember that this structure can have implicit and explicit groups as well.


If you pass DDF_INFO, the DD_FIELD subroutine reads the specified field. If that field is not found, the relevant error code is returned in the control structure. If it is found, the field name is recorded in the control structure and general information is returned in f_info.


Once a field has been selected, the DDF_TEXT function is valid. The DDF_TEXT function is used to obtain textual or variable‑length information about the field. For each type of textual information, a corresponding field in the f_info record is non‑zero. For example, if the fi_desc field in the f_info record is non‑zero, a short description exists for the field. If you pass DDF_TEXT along with the non‑zero field, the corresponding textual information is returned.


If you pass DDF_GROUP, the DD_FIELD subroutine sets the context to group level name if name is an explicit group within the current level. (An explicit group is a field definition which has the group flag set, but does not reference another structure.) All subsequent calls to DD_FIELD will access fields at that group level until DD_FIELD is called with the DDF_ENDGROUP function.

If name is not found at the current level, the relevant error code is returned in the control structure. If it is found, but is not an explicit group, context will not be changed.

If you pass DDF_ENDGROUP, the DD_FIELD subroutine resets the context to the current level’s parent. If the current level is the structure, the context is not changed.