KC_GET_OBJECT allows you to query information on all objects in the configuration and to query the application parameters.
Different kinds of information can be queried. You can control the type of information UTM shall return using the subopcode1 parameter.
The following information can be returned by UTM:
A list of the names of objects of an object type (subopcode1=KC_NAME or KC_NAME_NEXT).
Properties, status and statistical information on the objects of an object type (subopcode1=KC_ATTRIBUTES or KC_ATTRIBUTES_NEXT).
Properties are understood here to mean the parameters that have been set during the configuration of the objects. UTM returns the current values of these parameters, so any modifications by means of administration functions will be reflected in the data returned.
Status information describes the current status of an object, e.g. whether a connection is currently being set up or a user is currently signed on.
Statistical information includes counter values and internally measured wait times. UTM returns the following values, for example: the number of messages that the application has exchanged with a partner application of a client since its start, the number of messages being stored temporarily in a partner-specific message queue or the number of program unit runs that have been started using a transaction code.
The properties of an object and status and statistical information on an object are returned by UTM in the data area in the data structure for the object type (see "Data structures for describing object properties"). If UTM returns information on several objects, then UTM stores an array of data structures for the object type in the data area.
Where the properties of an object are discussed in the following text, this refers to object properties, status and statistical information.
The current settings for the application parameters
(subopcode1= KC_APPLICATION_PAR)The values returned by UTM are dependent on the parameter type you have specified in obj_type. You can, for example, choose between the maximum values of the application set during the KDCDEF generation, the system parameters, the current timer settings or statistical information on the current application load. In point obj_type in this chapter is a list of the parameter types you may select from.
For each parameter type there is a data structure in which UTM returns the application parameters queried. The data structures are described in "Data structures used to describe the application parameters".
Controlling the output of object names and object properties
UTM returns the object names sorted alphabetically. Accordingly, the properties of the objects are also returned in order of the object names. In subopcode2 you can specify if UTM is to return the names in ascending (KC_ASCENDING) or descending (KC_DESCENDING) alphabetical order.
Because the amount of information returned from a query of all objects of an object type can be very large, you should limit the amount of information requested. You have the following options available to limit the amount of information:
You can specify the point in the alphabetical list at which output is to start in the identification area. You can enter any string for this purpose.
If the string does not correspond to any object name of the object type specified, then UTM starts the output at the next object in the list, meaning the next highest or next lowest object alphabetically, depending on what you specified in subopcode2.
If the string in the identification area corresponds to an object name, then the starting point of the output is dependent on subopcode1:
for subopcode1=KC_NAME and KC_ATTRIBUTES, the output begins with this object.
for subopcode1=KC_NAME_NEXT and KC_ATTRIBUTES_NEXT, the output begins with the next object, meaning the next highest or next lowest object alphabetically, depending on what you specified in subopcode2.
The list of names or properties output will extend at most to the last (for subopcode2=KC_ASCENDING) or to the first (for subopcode2= KC_DESCENDING) object in the alphabetically ordered list of objects.
If the names or properties of the objects are to be read starting with the first object alphabetically of an object type, then you must specify subopcode2=KC_ASCENDING and set the identification area to binary zero.
If the names or properties of the objects are to be read in alphabetically descending order starting with the last object of an object type, then you must specify subopcode2=KC_DESCENDING and pass the string X'FF...‘ in the identification area.
In the obj_number field of the parameter area you can specify the maximum number of objects for which UTM is to return information.
In the selection area you can pass selection criteria to UTM.
UTM will then only return information on those objects meeting the specified selection criteria. A selection criterion is an object property. You could then, for example, output all the names of clients/printers that are currently connected to the application (obj_type =KC_PTERM). A list of all the selection criteria that you can specify can be found in section "Selection area" in this chapter.
Using selection criteria, you can target specific objects for selection and can therefore limit the amount of data returned.
The use of selection criteria does, however, influence the performance of the call, especially if only object names are queried. UTM must then read and check the properties for each object to see if each property satisfies its selection criterion. This means that, in this case, a call using selection criteria results in much more work than a call without selection criteria.
The following should be observed when querying information
When querying object names or object properties, information is also returned for objects that have been marked as deleted. You can limit the output to those objects not deleted using the selection criterion delete='N'. With the selection criterion delete='Y', you can also output all objects of the object type that have been deleted.
Note in the case of UTM cluster applications (Unix, Linux and Windows systems):
In UTM cluster applications, information is only supplied concerning the objects of the node application at which the call is executed.
The specifications KC_NO_READ_GSSBFILE and KC_NO_READ_USERFILE in subopcode2 allow you to determine whether or not the cluster GSSB file or cluster user file are accessed on follow-up calls for objects of type GSSB or USER. This makes it possible to improve performance when there are a large number of follow-up calls.
If subopcode2=KC_NO_READ_GSSBFILE or KC_NO_READ_USERFILE then the objects are always supplied in ascending order.
This improved performance is coupled with a level of uncertainty regarding the information that is returned by the follow-up calls. Since the data is not read again from the file, it may not be up-to-date.
Possible applications
You should consider the following points when using the subopcodes KC_... and KC_..._NEXT:
You should use KC_ATTRIBUTES or KC_NAME if you want to check whether or not an object with the object name specified already exists. To do this, specify the object name you want in the identification area and enter obj_number=1. The return code, with which you can determine whether an object exists (sub-return code = KC_SC_SAME) or not (sub-return code = KC_SC_NEXT), is evaluated after the call.
You can use KC_ATTRIBUTES or KC_NAME as the "starting point" of a succession of queries if you want to query the object names starting with a certain string but do not know if an object exists for this string.
For example, the string 'Sbbbbbbb' (b = blank) can be specified as the name if the objects are to be read starting with the first object name that begins with an "S" (as long as it is ensured that the binary representation of spaces is lexicographically smaller than the representation of letters and digits).
In a follow-up call in which you have specified in the identification area that the last object read in the previous call is to be the new starting point (successive query), then KC_ATTRIBUTES and KC_NAME are not suitable for use. For these parameter values the object name specified will be returned. If obj_number=1 was specified and you are executing a successive query, then this same object will always be read.
In this case, you must specify KC_ATTRIBUTES_NEXT or KC_NAME_NEXT. The following object will then be read as the first object.
You will find an example of a successive query of objects in chapter "KC_GET_OBJECT - Query information".
 | KDCINF (chapter "KDCINF - Request information on objects and application parameters") |
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area 1 | identification | selection | data | |
Output the names of all objects of a certain object type | subopcode1: | Name of the object with/after which the output of names is to begin | —— | A pointer to a data area for the data returned by UTM must be passed in the call. |
Output the names of all objects of a certain type with certain properties | Selection criteria used by UTM to limit the amount of data output | |||
Output properties and statistical information of objects of a certain type with certain properties | subopcode1: | |||
Output properties and statistical information of objects of a certain type | subopcode1: | —— | ||
Output application | subopcode1: | —— | —— | |
1 The operation code KC_GET_OBJECT must be specified in the parameter area in all cases.
Parameter settings | |
Parameter area | |
Field name | Contents |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_GET_OBJECT |
KC_NAME_NEXT | |
KC_ASCENDING | |
Object type | |
Number of objects | |
Length of the object name in the identification area | |
Length of the data in the selection area | |
Length of the data area | |
Object name/ — | |
Data structure of the object type with selection criteria / — | |
Data area | |
— | |
KDCADMI call |
KDCADMI (¶meter_area, &identification_area, &selection_area, &data_area) or |
Data returned by UTM | |
Parameter area (starting from "retcode") | |
Field name | Contents |
Return code | |
Number of objects | |
Length of the return data | |
Data structures of the object or parameter type / array of object names | |
subopcode1
In subopcode1 you specify the type of information to be returned by UTM. You can specify the following values:
KC_NAME
UTM is to return the names of objects of the object type obj_type.
If the string specified in the identification area matches an object name, then the output is to begin with the name of this object.
If the string in the identification area does not match an object name of the object type specified, then UTM is to begin the output with the next object, i.e. with the next highest object alphabetically for subopcode2=KC_ASCENDING or the next lowest object alphabetically for subopcode2= KC_DESCENDING.
KC_NAME_NEXT
UTM is to return the names of objects of the object type obj_type.
The output is to begin with the object name following the string specified in the identification area, i.e. with the next highest object alphabetically for subopcode2=KC_ASCENDING or the next lowest object alphabetically for subopcode2= KC_DESCENDING (see also point ).
KC_ATTRIBUTES
UTM is to return properties of objects of the object type obj_type.
If the string specified in the identification area matches an object name, then the output is to begin with the properties of this object.
If the string in the identification area does not match an object name of the object type specified, then UTM is to begin the output with the next object, i.e. with the next highest object alphabetically for subopcode2=KC_ASCENDING or the next lowest object alphabetically for subopcode2= KC_DESCENDING.
KC_ATTRIBUTES_NEXT
UTM is to return properties of objects of the object type obj_type.
The output is to begin with the object whose name follows the name specified in the string, i.e. with the next highest object alphabetically for subopcode2=KC_ASCENDING or the next lowest object alphabetically for subopcode2= KC_DESCENDING.
KC_APPLICATION_PAR
UTM is to return the application parameters of the parameter type specified in obj_type.
subopcode2
The data you must specify in the subopcode2 field depends on the value specified in subopcode1.
For subopcode1=KC_APPLICATION_PAR you must set subopcode2 to binary zero (KC_NO_SUBOPCODE).
For KC_NAME_NEXT, KC_NAME, KC_ATTRIBUTES_NEXT, and KC_ATTRIBUTES, you must specify one of the two following values in subopcode2:
KC_ASCENDING,
UTM returns the information on the objects in alphabetically ascending order according to object name, i.e. the next highest name alphabetically.
KC_DESCENDING
UTM returns the information on the objects in alphabetically descending order according to object name, i.e. the next lowest name alphabetically.
KC_READ_NO_GSSBFILE
This value may only be specified in the case of follow-up calls in a UTM cluster application with object type=KC_GSSB.
If KC_READ_NO_GSSBFILE is specified, then UTM does not access the cluster GSSB file again but instead uses the data from the last call with KC_ASCENDING. This improves performance when reading GSSBs, see note below.
UTM returns the information on the GSSBs in ascending object name order.KC_READ_NO_USERFILE
This value may only be specified in the case of follow-up calls in a UTM cluster application with object type=KC_USER.
If KC_READ_NO_USERFILE is specified, then UTM does not access the cluster user file again but instead uses the data from the last call with KC_ASCENDING. This improves performance when reading large numbers of user IDs, see note.UTM returns the information on the user IDs in ascending object name order.
If, in UTM cluster applications, you read in GSSBs or user IDs with subopcode2=KC_ASCENDING or subopcode2=KC_DESCENDING then all the objects are read in locally from the cluster GSSB file or cluster user file and sorted. Each time you reread the GSSBs/user IDs with this subopcode2, all the GSSBs (max. 30000) or all the user IDs are again read in and sorted.
If you require a high performance level, only specify KC_ASCENDING for the first call and use KC_READ_NO_GSSBFILE or KC_READ_NO_USERFILE for all follow-up calls. However, this means that any changes made after the first call are not displayed.
obj_type
in the obj_type field you must specify the type of the objects or application parameters for which UTM is to return information. The data you must specify in obj_type depends on the value specified in subopcode1. Please consult the following table for the values allowed. The meanings of the object/parameter types are described in chapter "Description of the data areas to be supplied".
Object type / parameter type | Permissible specifications for subopcode1 = |
Object type: | KC_ATTRIBUTES, |
Object type: KC_CHARACTER_SET (on BS2000 Systems only) | KC_ATTRIBUTES, |
Object type: | KC_ATTRIBUTES |
Parameter type: | KC_APPLICATION_PAR |
In the case of obj_type=KC_USER, KC_USER_DYN1, KC_USER_DYN2 and KC_USER_FIX, please note the following:
The data structures kc_user_str, kc_user_fix_str, kc_user_dyn1_str and kc_user_dyn2_str are defined for the object types KC_USER, KC_USER_DYN1, KC_USER_DYN2 and KC_USER_FIX.
In stand-alone UTM applications, the data belonging to a user can always queried using kc_user_str structure.
The fields present in the three data structures kc_user_fix_str, kc_user_dyn1_str and kc_user_dyn2_str are also present in the data structure kc_user_str. This subdivision into three data structures was undertaken in order to make it possible to access specific user information values and consequently improve performance, in particular when reading user information in UTM cluster applications.
All the data relating to the cluster user file is located in the data structure kc_user_dyn2_str.
To read this data, openUTM must access the cluster user file. That is why, when reading user information in UTM cluster applications, you should preferably use the new object types and only call KC_USER_DYN2 if you currently need the data that this call returns.
Note the following for obj_type=OSI_ASSOCIATION:
For subopcode1=KC_NAME and KC_NAME_NEXT, UTM returns the names of the OSI TP associations set during KDCDEF generation. The names consist of an association prefix specified in an OSI-LPAP command and a serial number.
You can specify an association name in the identification area for these values of subopcode1.For subopcode1=KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT, UTM only returns the properties of associations that belong to a particular partner application and that have been or are currently being established. For this reason, you must specify the partner application as a selection criterion when calling the OSI-LPAP partner. You pass the data structure kc_osi_association_str containing the name of the OSI-LPAP partner in the selection area (see "kc_osi_association_str - Associations to OSI TP partner applications").
The properties of an association are not stored internally under the association name, but under an association ID assigned by UTM to an association as long as it is in existence. It is not possible to assign an association ID to the name of an association. UTM therefore interprets the string specified in the identification area (field kc_name8 in the union kc_id_area) as an association ID. UTM returns the properties of the active associations to a partner application sorted according to the association IDs. It is not possible to query the properties of an association name.
Note the following for obj_type=KC_HTTP_DESCRIPTOR:
subopcode2 must be set to KC_ASCENDING.
The identification area can be used.
The selection area must not be specified.
The output of the information on the HTTP descriptors is not sorted alphabetically according to the names but in the order in which the statements are evaluated when an HTTP request arrives.
Note the following for obj_type=KC_CHARACTER_SET:
subopcode2 must be set to KC_ASCENDING.
The identification area can be used.
The selection area must not be specified.
The output of the Information on character sets is sorted alphabetically according to the names.
Note the following for obj_type=KC_SUBNET:
subopcode2 must contain binary zero (KC_NO_SUBOPCODE).
The identification area can be used.
The selection area may not be specified.
The output of the information on the subnets is not sorted according to the subnet names (mapped_name), but takes place in the order in which the statements were specified during generation - separated according to IPv4 and IPv6 subnets.
This corresponds to the order in which the SUBNET entries are evaluated when a connection is established from outside.
obj_number
In obj_number you can specify the number of objects for which UTM is to return information. The following can be specified:
For subopcode1=KC_NAME,KC_NAME_NEXT, KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT:
obj_number specifies the maximum number of objects for which UTM is to return information.
If you specify obj_number=0, then UTM will return information on as many objects as will fit in the data area, or less if there are no more objects of the object type available.
In the case of obj_type=KC_CLUSTER_NODE, please note the following:
If you specify an obj_number > 32, openUTM sets obj_number to 32.For subopcode1=KC_APPLICATION_PAR you must always specify obj_number=0.
id_lth
The data you must specify in the id_lth is dependent on the data contained in the subopcode1 field:
For subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT:
In id_lth you must specify the length of the data structure you have passed to UTM in the identification area.
For subopcode1=KC_APPLICATION_PAR you must always set id_lth=0. The contents of the identification area are irrelevant.
select_lth
In select_lth you must specify a value !=0 if you want to pass selection criteria to UTM in the selection area.
For subopcode1=KC_APPLICATION_PAR you may not pass any selection criteria to UTM and must therefore always set select_lth=0 in this case.
For subopcode1= KC_ATTRIBUTES or KC_ATTRIBUTES_NEXT and obj_type= KC_OSI_ASSOCIATION, you must pass the data structure kc_osi_association_str with the name of an OSI-LPAP partner in the selection area. In this case, the length of the data structure kc_osi_association_str is to be specified in select_lth.
For obj_type=KC_SUBNET and KC_HTTP_DESCRIPTOR, you must always specify select_lth=0.
data_lth
In data_lth you must specify the length of the data area that you are providing to UTM for returning the information queried.
For subopcode1= KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT, the following is true:
If you specify obj_number
!=0, then the data area provided for returning the number of objects requested must be large enough. For obj_number=n (see .) you must specify in data_lth a minimum length of (n* maximum length of the object name) or (n * length of the data structure of the object type in obj_type).For subopcode1=KC_APPLICATION_PAR, you must specify at least the length of the data structure of the parameter type set in obj_type.
Identification area
The data you must specify in the identification area is dependent on the data contained in the subopcode1 field and the value of obj_type:
For subopcode1=KC_NAME,KC_NAME_NEXT, KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT:
You must pass a string to UTM in the identification area. The string specifies the object at which UTM is to begin outputting information.
You can also pass binary zero or a string containing non-printable characters in the identification area. UTM takes the string as it is and searches for the next highest (for subopcode2=KC_ASCENDING) or next lowest (for subopcode2= KC_DESCENDING) object name.
You place a kc_id_area union (see section "Identification area" in chapter "Description of the data areas to be supplied") in the identification area. The string must be passed in the union element that belongs to the object type specified in obj_type.
For obj_type=KC_PROGRAM and KC_LOAD_MODULE:
you pass the string in the element kc_name32. The name must be left-justified, and the rest of the field must either be padded with blanks or end with the null byte (\0).
The string specified does not have to be an object name.For obj_type=KC_CON and KC_PTERM:
you must pass the string in the union element kc_long_triple_str. A name triplet (object name, computer name, name of the local application) can be specified in kc_long_triple_str. The object name and the name of the local application can be up to 8 characters long, the computer name up to 64 characters.
You can specify any string for each of the three names. The name does not need to exist. It is sufficient just to specify a string for the object name, you do not need to specify the computer name and the name of the local application. You may set these to binary zero.
When evaluating the strings in the identification area, UTM interprets the three names as a 80 character long object name. The starting point of the output is determined accordingly.For obj_type=KC_MUX:
you must pass the string in the union element kc_triple_str. A name triplet (object name, computer name, name of the local application) can be specified in kc_triple_str. Each of the names can be up to 8 characters long.
You can specify any string for each of the three names. The name does not need to exist. It is sufficient just to specify a string for the object name, you do not need to specify the computer name and the name of the local application. You may set these to binary zero.
When evaluating the strings in the identification area, UTM interprets the three names as a 24 character long object name. The starting point of the output is determined accordingly.With obj_type=KC_DB_INFO
you can specify a number to identify a database in the union element kc_name2. This number represents the databases in the order in which they were generated in the KDCDEF run. If you specify a different string, the call is rejected.For obj_type=KC_SFUNC
you can specify a valid function key in the union element kc_name4. If you use a different string, the call will be rejected.
The following options are valid:
on BS2000 systems: F1 to F20 and K1 to K14
on Unix, Linux and Windows systems: F1 to F20
If you do not make an entry in the identification area, UTM will return data on all function keys.
If you enter a valid function key, UTM will start output with that function keyFor obj_type = KC_TACCLASS:
you can specify the values of an existing TAC class, a LOW VALUE or a HIGH VALUE in the union element kc_name2. If you specify any other string, the call will be rejected.For obj_type = KC_OSI_ASSOCIATION
you must pass the string in the union element kc_name8.
For subopcode1=KC_NAME and KC_NAME_NEXT,
UTM interprets the string as the name of an OSI TP association.
For subopcode1= KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT,
UTM interprets the string as an association ID. See the description in point obj_type.For obj_type=KC_CLUSTER_NODE
you must pass LOW VALUE, HIGH VALUE or empty fields in the identification area. Otherwise the call is rejected. No specific node is addressed. Choose a value for data_lth that is large enough for information to be passed to all the nodes.
For all other object types, the string must be passed in the union element kc_name8. The string must be stored left-justified and the rest of the field is to be padded with blanks.
The string specified does not have to be an object name.If the identification area is used for obj_type=KC_SUBNET, the name specified there must be an object name, i.e. it must correspond to a generated subnet name (mapped_name) as the information on the subnets is not sorted in alphabetical order when it is stored but in the order specified in the generation. If no generated mapped_name is specified, KC_MC_NO_ELT is returned as the return code with subcode KC_SC_NOT_EXISTENT.
- If the identification area is used for obj_type=KC_HTTP_DESCRIPTOR, the name specified there must be an object name, i.e. it must correspond to a generated HTTP descriptor name as the information on the HTTP descriptors is not sorted in alphabetical order but in the order they are evaluated when an HTTP request is received. If no generated name is specified, KC_MC_NO_ELT is returned as the return code with subcode KC_SC_NOT_EXISTENT.
For subopcode1=KC_APPLICATION_PAR the null pointer should be passed for the identification area.
Selection area
In the selection area, if select_lth !=0, then you must pass the data structure of the object type to UTM together with the selection criteria. The rest of the fields in the data structure must be set to binary zero.
The data structures are described in section "Data structures for describing object properties". The name of each data structure is created as follows: data structure "typ _str" belongs to the object type "TYP", so, for example, the data structure kc_lterm_str belongs to KC_LTERM.
If select_lth = 0, the selection area, and therefore the selection criteria, are not evaluated.
A selection criterion is an object property. If selection criteria are specified, then UTM executes a selective search of the objects. Only information on the objects meeting the selection criteria is returned. The selection criteria you may specify for each object type is listed in the following text.
Possible selection criteria
obj_type=KC_CON: connections to LU6.1 partner applications
In the selection area you pass the data structure kc_con_str with the selection criteria. The following data may be specified:
Field name
Meaning
connect_mode='Y'
UTM returns information on LU6.1 connections currently open.
pronam_long
UTM returns information on LU6.1 connections to partner applications that are running on a certain computer. You specify the name of the computer in pronam_long.
delete
delete='Y':
UTM returns information on LU6.1 connections that were deleted from the configuration.
delete='N':
UTM returns information on LU6.1 connections that were not deleted from the configuration.You can also specify multiple selection criteria together, meaning you can specify multiple fields at the same time.
obj_type=KC_LPAP: LPAP partner
In the selection area, you pass the data structure kc_lpap_str with the selection criteria. The following specifications are permitted:
Field name
Meaning
master
master contains the name of a master LPAP in an LPAP bundle.
UTM returns information on the slave LPAPs in this LPAP bundle.obj_type=KC_LSES: sessions to LU6.1 partner applications
In the selection area you pass the data structure kc_lses_str with the selection criteria. The following data may be specified:
Field name
Meaning
connect_mode='Y'
UTM returns information on sessions for which a transport connection is currently established.
lpap
UTM returns information on sessions that are assigned to a certain LU6.1 partner application. You specify the name of the LPAP partner assigned to this partner application in lpap.
delete
delete='Y':
UTM returns information on sessions that were deleted from the configuration.
delete='N':
UTM returns information on sessions that were not deleted from the configuration.You can also specify multiple selection criteria, meaning you can specify multiple fields at the same time.
obj_type=KC_LTERM: LTERM partner
In the selection area, you pass the data structure kc_lterm_str with the selection criteria. The following specifications are permitted:
Field name
Meaning
master
master contains the name of a master LTERM in an LTERM bundle:
UTM returns information on the slave LTERMs of the LTERM bundle for the specified master LTERM.
master contains the name of a primary LTERM in an LTERM group:
UTM returns information on the group LTERMs of the LTERM group for the specified primary LTERM.delete
delete='Y':
UTM returns information on LTERMs that were deleted from the configuration.
delete='N':
UTM returns information on LTERMs that were not deleted from the configuration.You can also specify both selection criteria, meaning you can specify both fields at the same time.
obj_type=KC_MUX: multiplex connections (only on BS2000 systems)
In the selection area you pass the data structure kc_mux_str with the selection criteria. The following data may be specified:
Field name
Meaning
connect_mode='Y'
UTM returns information on multiplex connections for which a transport connection to the message router is currently established.
pronam
UTM returns information on multiplex connections that are defined for message routers on a certain computer. You specify the name of the computer in pronam.
You can also specify both selection criteria, meaning you can specify both fields at the same time.
obj_type=KC_OSI_ASSOCIATION: associations to OSI TP partner applications
For subopcode1= KC_NAME and KC_NAME_NEXT, no selection criterion may be specified.
For subopcode1= KC_ATTRIBUTES and KC_ATTRIBUTES_NEXT, you must pass the following selection criterion to UTM (see the description under point obj_type). To do this, pass the data structure kc_osi_association_str in the selection area with the following data:
Field name
Meaning
osi_lpap
UTM returns information on associations that are assigned to a certain OSI TP partner application. You specify the name of the OSI-LPAP partner assigned to this partner application in osi_lpap.
obj_type=KC_OSI_LPAP: Properties of OSI TP partner applications
In the selection area, you pass the data structure kc_osi_lpap_str with the selection criteria. The following specifications are permitted:
Field name
Meaning
master
master contains the name of a master LPAP in an OSI-LPAP bundle:
UTM returns information on the slave LPAPs of the LPAP bundle for the specified master LPAP.obj_type=KC_PROGRAM: program units
In the selection area you pass the data structure kc_program_str with the selection criteria. The following data may be specified:
Field name
Meaning
load_module
UTM returns information on program units and VORGANG exits that are linked into a certain load module / shared object/DLL. You specify the name of the load module / shared object /DLL in load_module.
delete
delete='Y':UTM returns information on program units that have been deleted from the configuration.
delete='N': UTM returns information on program units that have not been deleted from the configuration.You can also specify both selection criteria, meaning you can specify both fields at the same time.
obj_type=KC_PTERM: clients and printers
In the selection area you pass the data structure kc_pterm_str with the selection criteria. The following data may be specified:
Field name
Meaning
lterm
Is only useful for printers:
UTM is to return information on the printers in a printer pool. The printers in a printer pool are assigned to the same LTERM partner.
The name of the LTERM partner is to be specified in lterm.connect_mode='Y'
UTM returns information on clients/printers that are currently connected to the application.
pronam_long
UTM returns information on clients and printers running on a certain computer or which are connected to this computer. You specify the name of the computer in pronam_long.
delete
delete='Y':UTM returns information on clients and printers that have been deleted from the configuration.
delete='N': UTM returns information on clients and printers that have not been deleted from the configuration.You may only specify the selection criterion lterm alone. All other fields of the data structure must then be set to binary zero.
Either connect_mode and pronam_long or pronam_long and delete can be specified together. connect_mode and delete cannot be set at the same time.obj_type=KC_USER, KC_USER_DYN1, KC_USER_DYN2, KC_USER_FIX:
user IDsIn the selection area you pass the data structure kc_user_str or kc_user_dyn1_str with the selection criteria. The following data may be specified:
Field name
Meaning
connect_mode='Y'
UTM returns information on user IDs with which a user/client is currently signed on to the application.
delete
delete='Y':
UTM returns information on user IDs that have been deleted from the configuration.
delete='N':
UTM returns information on user IDs that have not been deleted from the configuration.The selection criteria must not be specified together, i.e. only one field may be set per call.
obj_type=KC_LTAC or KC_TAC: transaction codes.
In the selection area you pass the data structure kc_ltac (KC_LTAC) or kc_tac_str (KC_TAC) with the selection criteria. The following data may be specified:
Field name
Meaning
delete
delete='Y':UTM returns information on transaction codes that have been deleted from the configuration.
delete='N': UTM returns information on transaction codes that have not been deleted from the configuration.
retcode
in the retcode field UTM outputs the return codes of the call. In addition to the return codes listed in section "Return codes", the following return codes can also be returned.
Main code = KC_MC_OK The call was processed without error. Subcodes: |
KC_SC_SAME subopcode1 = KC_NAME or KC_ATTRIBUTES was set, and an object exists that corresponds to the object name specified in the identification area. |
KC_SC_NEXT subopcode1 = KC_NAME_NEXT or KC_ATTRIBUTES_NEXT was set. |
Main code = KC_MC_LAST_ELT The call was processed without error, but fewer objects were read than were queried, and the last object has already been reached. Subcodes: |
KC_SC_SAME subopcode1 = KC_NAME or KC_ATTRIBUTES was specified. An object corresponding to the object name specified in the identification area exists. |
KC_SC_NEXT subopcode1 = KC_NAME_NEXT or KC_ATTRIBUTES_NEXT was set. |
Main code = KC_MC_NO_ELT subopcode1 = KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES or KC_ATTRI-BUTES_NEXT was specified. There is no element or no next element corresponding to the object name specified. Subcode: |
KC_SC_NO_INFO |
KC_SC_NOT_EXISTENT (only on Unix, Linux and Windows systems) The object name specified in the identification area was not found in obj_type. |
Main code = KC_MC_MEMORY_INSUFF UTM cannot execute the function because that would require more internal storage space than UTM has available. Subcode: |
KC_SC_NO_INFO |
Main code = KC_MC_REJECTED The call was rejected by UTM because no object of the specified type exists. Subcode: |
KC_SC_NOT_GEN If obj_type=KC_DB_INFO, then no database was generated during the KDCDEF generation. |
KC_SC_NO_F_KEYS_GENERATED You specified obj_type=KC_SFUNC, but no function keys were generated for the application. |
KC_SC_CCFG_FILE_READ_ERROR Only in UTM cluster applications: |
KC_SC_CCFG_INVAL_NODE_BUFF_LTH Only in UTM cluster applications: |
KC_SC_CCFG_FILE_LOCK_ERROR Only in UTM cluster applications: |
KC_SC_CCFG_RT_CODE_NOT_OK Only in UTM cluster applications: |
KC_SC_CUSF_USER_NOT_FOUND Only in UTM cluster applications: |
KC_SC_CUSF_RT_CODE_NOT_OK Only in UTM cluster applications: |
Main code = KC_MC_NOT_EXISTENT The object specified does not exist. Subcode: |
KC_SC_NO_INFO obj_type=KC_DB_INFO, KC_SFUNC or KC_TACCLASS: |
Main code = KC_MC_SEL_INVALID Invalid data was specified in the selection area. Subcode: |
KC_SC_NO_INFO |
number_ret
After a call with subopcode1=KC_NAME, KC_NAME_NEXT, KC_ATTRIBUTES or KC_ATTRIBUTES_NEXT, number_ret contains the number of objects for which UTM has returned information in the data area.
If no more objects corresponding to the string specified in the identification area exist, then UTM returns number_ret=0 and data_lth_ret=0 and sets the corresponding return code.
After a call with subopcode1=KC_APPLICATION_PAR, UTM always returns number_ret=0.
data_lth_ret
In data_lth_ret UTM returns the length of the data that UTM has stored in the data area.
The length of the data returned is:
for subopcode1=KC_NAME, KC_NAME_NEXT:
number of objects * length of the name field belonging to the object typefor subopcode1= KC_ATTRIBUTES or KC_ATTRIBUTES_NEXT:
number of objects * length of the data structure of the object typefor subopcode1=KC_APPLICATION_PAR:
length of the data structure of the parameter type
If no object or no more objects corresponding to the string specified in the identification area exist, then UTM returns data_lth_ret=0 and sets the corresponding return code.
Data area
in the data area UTM returns the information queried.
subopcode1=KC_NAME, KC_NAME_NEXT:
UTM returns an array of object names. The object names are ordered alphabetically in the array in ascending (for subopcode2=KC_ASCENDING) or descending (for subopcode2=KC_DESCENDING) order.
The length of the individual names corresponds to the length of the name field in the data structure of the object type.
For obj_type=KC_CON and KC_PTERM, UTM returns an array of name structures with the following format:
struct kc_long_triple_str
char p_name[8];char pronam[64];char bcamappl[8];For obj_type=KC_MUX, UTM returns an array of name structures with the following format:
struct kc_triple_str
char p_name[8];char pronam[8];char bcamappl[8];The three fields of the data structure contain the following for each of the objects:
p_name
object name, i.e. the name of the connection, client, printer or multiplex connection
pronam
Name of the computer on which the object is located
bcamappl
Name of the local application via which the connection to this object has been established.
For subopcode1=KC_NAME_NEXT the name array always begins with the object name that is the next highest or next lowest alphabetically, depending on the value of subopcode2, with respect to the string specified in the identification area.
There are two cases for subopcode1=KC_NAME:If an object name exists that corresponds to the string you have specified in the identification area, then the name array begins with this object name. UTM returns the KC_SC_SAME return subcode.
If the string specified in the identification area does not correspond to an object name, then, just as with subopcode1=KC_NAME_NEXT, the name array begins with the object name that is the next highest or next lowest alphabetically, depending on the value of subopcode2, with respect to the string specified in the identification area. UTM returns the KC_SC_NEXT return subcode.
subopcode1= KC_ATTRIBUTES or KC_ATTRIBUTES_NEXT:
UTM places an array of data structures of the object type in the data area. Each data structure contains the properties of an object. The data structures are placed one after the other and are put in ascending or descending alphabetical order according to the object names, depending on the value of subopcode2.
The data structures are described in section "Data structures for describing object properties". The name of each data structure is created as follows: the data structure "typ_str" belongs to the object type "TYP", so, for example, the data structure kc_lterm_str belongs to KC_LTERM.
In the data structures, the fields that were not specified when the object was added to the configuration contain the default values, blanks or '0'. Fields only relevant to other operating systems are set to binary zero.
The object with which the array begins depends on the value of subopcode1 and on the name specified in the identification area.
For subopcode1=KC_ATTRIBUTES_NEXT the array begins with the object that is the next highest or next lowest alphabetically, depending on the value of subopcode2, with respect to the string specified in the identification area.
There are two cases for subopcode1=ATTRIBUTES:
If an object name exists that corresponds to the string you have specified in the identification area, then the name array begins with this object name. UTM returns the KC_SC_SAME return subcode.If the string specified in the identification area does not correspond to an object name, then, just as with subopcode1=KC_ATTRIBUTES_NEXT, the name array begins with the object name that is the next highest or next lowest alphabetically, depending on the value of subopcode2, with respect to the string specified in the identification area. UTM returns the KC_SC_NEXT return subcode.
subopcode1= KC_APPLICATION_PAR:
UTM places the data structure of the parameter type specified in obj_type in the data area. UTM returns the application parameters requested in the data structure.
The data structures are described in section "Data structures used to describe the application parameters". The name of each data structure is created as follows: the data structure "typ
_str" belongs to the object type "TYP", so, for example, the data structure kc_max_par_str belongs to KC_UKC_MAX_PAR.
Example of a successive query with KC_ATTRIBUTES_NEXT
Task
All information on user IDs whose names begin with "S" is to be read. It is assumed in the following that such user IDs exist.
Solution
First KC_GET_OBJECT call:
(It is assumed that n objects are found by this call, i.e. that n_ret=n.)
Data to be entered in the parameter area: |
version=KC_ADMI_VERSION_1 |
Data to be entered in the identification area: 'Sbbbbbbb' or 'S\0' (b = blank, \0 = null byte in C) |
Data to be entered in the selection area: none |
Data to be entered in the data area: none |
Data returned by UTM:
Data returned in the parameter area: |
retcode= KC_MC_OK with subcode KC_SC_SAME or KC_SC_NEXT number_ret=n_ret data_lth_ret=n_ret*sizeof(struct kc_user_str) |
Data returned in the data area: n_ret * data structure kc_user_str with the properties of the user IDs |
If the last user ID returned still begins with "S", then another call must be made.
Second KC_GET_OBJECT call:
(Data to be entered which differs from that in the first call is underlined)
Data to be entered in the parameter area: |
version=KC_ADMI_VERSION_1 |
Data to be entered in the identification area: Name of the last user ID returned by UTM in the first call |
Data to be entered in the selection area: none |
Data to be entered in the data area: none |
Data returned by UTM:
Data returned in the parameter area: |
| retcode=KC_MC_OK with subcode KC_SC_NEXT 1 number_ret=n_ret (<= n) data_lth_ret=n_ret * sizeof(struct kc_user_str) |
Data returned in the data area: n_ret * data structure kc_user_str with the data of the user IDs |
1 | The return codes KC_MC_LAST_ELT (if less than n objects were found) and KC_MC_NO_ELT (if no further object was found) can also occur. |
The second call is repeated until all user IDs beginning with "S" have been read. Whether or not all user IDs beginning with "S" have been read can be determined by evaluating the return data. This means that if the name of the last user ID returned by UTM begins with "S", then the call must be repeated again. If it does not begin with "S" or if number_ret != obj_number in the last call, then all user IDs beginning with "S" have been read.