|
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:
- DDF_LIST and DDF_SLIST enable you to retrieve the structure’s field names.
- DDF_INFO enables you to retrieve general information about a field.
- DDF_TEXT enables you to retrieve textual information about a field.
- DDF_GROUP and DDF_ENDGROUP enable you to establish group context.
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.
