|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
xcall DD_KEY(dcs, DDK_LIST, names_req, array, [start][, #names])
or
xcall DD_KEY(dcs, DDK_SLIST, names_req, array, [start][, #names])
or
xcall DD_KEY(dcs, DDK_INFO, name, k_info)
or
xcall DD_KEY(dcs, DDK_TEXT, field, data)
Arguments
dcs
The repository control structure.
DDK_LIST
Returns the current structure’s key names in alphabetical order.
names_req
The number of key names requested. (d2)
array
Returned with the array of key names. ((*)a30)
start
(optional) Contains the key name at which to start. (a30)
#names
(optional) Returned with the number of key names. (d2)
DDK_SLIST
Returns the current structure’s key names in sequence order.
DDK_INFO
Returns general key information.
name
The unique key name. (a30)
k_info
Returned with the key data. See the k_info record definition in the ddinfo.def file.
DDK_TEXT
Returns textual information about the current key.
field
A field in the k_info record that indicates what type of textual information should be returned in data (if the field is non-zero):
ki_desc = Short description. (a40)
ki_nullval = Null key value. (a255)
data
Returned with the requested textual data.
Discussion
The DD_KEY subroutine returns information about keys for the current structure. There are four ways to call DD_KEY:
- DDK_LIST and DDK_SLIST enable you to retrieve the structure’s key names.
- DDK_INFO enables you to retrieve general information about a key.
- DDK_TEXT enables you to retrieve textual information about a key.
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 keys that exist.
DDK_LIST and DDK_SLIST
If you pass DDK_LIST or DDK_SLIST, the DD_KEY subroutine returns an array of key names for the current structure. If you pass DDK_LIST, the names are returned in alphabetical order, starting with either the first name found or the specified name. If you pass DDK_SLIST, the names are returned in sequence order (the order defined in the structure), starting with either the first name found or the specified name. DD_KEY returns as many key 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.
DDK_INFO
If you pass DDK_INFO, this subroutine reads the specified key. If that key is not found, the relevant error code is returned in the control structure. If it is found, general key information is returned in k_info.
DDK_TEXT
Once a key has been selected, the DDK_TEXT function is then valid. The DDK_TEXT function is used to obtain textual or variable-length information about the key. For each type of textual information, a corresponding field in the k_info record is non-zero. For example, if the ki_desc field in the k_info record is non-zero, a short description exists for the key. If you pass DDK_TEXT along with this non-zero field, the corresponding textual information is returned.
