DD_STRUCT

Retrieve structure information

xcall DD_STRUCT(dcs, DDS_INFO, name, s_info[, s_name])

xcall DD_STRUCT(dcs, DDS_TEXT, field, data)

xcall DD_STRUCT(dcs, DDS_FILS, names_req, array, [start][, #names])

Arguments

dcs

The repository control structure.

DDS_INFO

Returns general structure information and sets the current structure.

name

The unique structure name. It can be the name of an alias structure. (a30)

s_info

Returned with the structure data (including file type, record size, number of fields, keys, relations, formats, number of files to which it is assigned, name of the first file to which it is assigned, and structure tag information). See the s_info record definition in ddinfo.def.

s_name

(optional) Returned with the name of the aliased structure, if name is an alias structure name.

DDS_TEXT

Returns textual information about the current structure.

field

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

si_desc = Short description. (a40)

si_ldesc = Long description. (a1800)

si_utext = User-defined text string. (a60)

data

Returned with the requested textual data.

DDS_FILS

Returns the list of files to which a structure is assigned.

names_req

The number of assigned file definition names requested. (d3)

array

Returned with the array of assigned file definition names. ((*)a30)

start

(optional) Contains the assigned file definition name at which to start. (a30)

#names

(optional) Returned with the number of assigned file definition names. (d3)

Discussion

The DD_STRUCT subroutine returns information about structures. It also sets the current structure. There are three ways to call DD_STRUCT:

DDS_INFO enables you to retrieve general information about a structure.
DDS_TEXT enables you to retrieve textual information about a structure.
DDS_FILS enables you to retrieve a structure’s list of assigned files.

DDS_INFO

If you pass DDS_INFO, the DD_STRUCT subroutine reads the specified structure. If that structure is not found, an error code is returned in the control structure. If it is found, information about the structure is recorded in the control structure and general information is returned in s_info.

The s_info record returns the total number of fields in the structure (including any groups) in si_nmflds. However, because si_nmflds is only a d3, if the field count is equal to or greater than 999, si_nmflds is set to 999, and your application must iterate through the structure and its groups to calculate the total field count using si_childct and fi_childct (which are what Repository uses internally to calculate the total).

The structure can be an alias structure, in which case the name of the aliased structure can be returned in s_name. Also, the structure name recorded in the control structure (the current structure) will be the name of the aliased structure.

Once you set a current structure with the DDS_INFO function, you can then use other subroutines to access information about the fields, keys, relations, formats, and tag associated with that structure. The DDS_TEXT and DDS_FILS functions also become valid.

DDS_TEXT

The DDS_TEXT function is used to obtain textual or variable-length information about the structure. For each type of textual information, a corresponding field in the s_info record is non-zero. For example, if the si_desc field in the s_info record is non-zero, a short description exists for the structure. If you pass DDS_TEXT along with the non-zero field, the corresponding textual information is returned.

DDS_FILS

If you pass DDS_FILS, this subroutine returns an array of file definition names to which this structure is assigned. If this structure is assigned to only one file, that file definition name is returned in s_info. The names are returned in the order in which the structure was assigned to them, starting with either the first one or the specified name. DD_STRUCT returns either as many file definition names as it finds or as you request, whichever is smaller. The actual number of names in the array can be returned in #names. You must ensure that the buffer passed is large enough to hold the number of names you are requesting.