DD_FIELD

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])

or

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

or

xcall DD_FIELD(dcs, DDF_INFO, name, f_info)

or

xcall DD_FIELD(dcs, DDF_TEXT, field, data)

or

xcall DD_FIELD(dcs, DDF_GROUP, name)

or

xcall DD_FIELD(dcs, DDF_ENDGROUP)

Arguments

dcs

The repository control structure.

DDF_LIST

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

names_req

The number of field names requested. (d3)

array

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

start

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

#names

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

DDF_SLIST

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

DDF_INFO

Returns general field information and sets the current field.

name

The unique field name. (a30)

f_info

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

DDF_TEXT

Returns textual information about the current field.

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)

data

Returned with the requested textual data.

DDF_GROUP

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

DDF_ENDGROUP

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

Discussion

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.

DDF_LIST and DDF_SLIST

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.

DDF_INFO

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.

DDF_TEXT

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.

DDF_GROUP and DDF_ENDGROUP

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.