List Registered Application Information (QSZLSTRA, QszListRegAppInfo) API

Required Parameter Group:

1	Application information path name for input	Input	Char(*)
2	Application information path name for output	Output	Char(*)
3	Continuation handle input	Input	Binary(4)
4	Continuation handle output	Output	Binary(4)
5	Error code	I/O	Char(*)

  Service Program Name: QSZRAIRA

  Default Public Authority: *EXCLUDE

  Threadsafe: No

The List Registered Application Information (QSZLSTRA, QszListRegAppInfo) API retrieves the results of a query of the IBM^® i Registered Application Information Repository. Data is returned as an XML document.

Authorities and Locks

Library authority (INPUT and OUTPUT): *EXECUTE
Authority for user space containing XML input document: *USE
Authority for user space containing XML output document: *CHANGE
User space lock (INPUT): *EXCLRD
User space lock (OUTPUT): *EXCL
Stream file directory authority (INPUT): *RX
Stream file directory authority (OUTPUT): *RWX
Authority for stream file containing XML input document: *R
Authority for stream file containing XML output document: *RW

Required Parameter Group

Application information path name input: INPUT; CHAR(*)
The path name of the object that contains the XML document with the information of the components to be listed by the API. This may be a path to a user space (*USRSPC) or a path to a stream file (*STMF). The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The information contained in this object must be given to the API as an XML document according to the data type definition (DTD). For a detailed description of the DTD, see Software components DTD. For a detailed description of the information that should be contained in this object, see XML document when listing component information.
Application information path name output: OUTPUT; CHAR(*)
The path name of the object that contains the XML document listing the results of the query. This may be a path to a user space (*USRSPC) or a path to a stream file (*STMF). The path name should be specified in the Qlg_Path_Name_T format. If a pointer is specified in the path name format, it must be 16-byte aligned. If not, unpredictable results may occur. For more information on this structure, see Path name format. The information contained in this object is returned to the API caller as an XML document according to the data type definition (DTD).
Continuation handle input: INPUT; BINARY(4)
This is a special value that should be used to request the remaining entries of a previous query when a user space was provided to return the component information, but the size of the space was not enough to hold the information. This value should be taken from the Continuation Handle Output parameter returned in the previous call. This parameter must be set to 0 on the first call to this API. When you specify a continuation handle for this parameter, all other parameters must have the same values as the call to the API that generated the continuation handle. Failure to do so may result in incomplete or inaccurate information.
Continuation handle output: OUTPUT; BINARY(4)
This value indicates whether the list returned is complete or if the space provided to hold the information being returned was not enough. If this value is 0, then the list is complete. If the value is different than 0, it means that only part of the information was returned, so a second call is needed to return the remaining information. Only complete components will be returned. If a component cannot fit in the space provided, the component will not be returned; that is, a complete XML document will be returned with as many <Component> tags as can fit in the space provided.
Error code: I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.

XML Document when listing component information

This object may be a stream file (*STMF) or a user space (*USRSPC) object. In either case, the contents of the object must be an XML document that conforms to the specified rules.

All elements and attributes defined in the data type definition (DTD) are allowed. See below for examples of possible queries. See Software components DTD for a detailed description of each element and attribute.

In addition, special characters can be used to increase query capabilities.

The percent sign (%) stands for an unknown string of 0 or more characters. Available options are:

%xxx	The ends with selection criteria, where xxx are the characters with which you want the attribute value to end.
xxx%	The starts with selection criteria, where xxx are the characters with which you want the attribute value to start.
%xxx%	The contains selection criteria, where xxx are the characters you want to be contained in your attribute value.

An underline character (_) stands for any single character.

If you do not specify any of these characters, it indicates that you want an exact match.

The rules to follow in your XML document to do the query are:

When product, version, component name, instance, feature or vendor are not present or are empty, it indicates that you want any match on those attributes. For example, if you do not specify ComponentVersion, ComponentName, Instance and ComponentVendor attributes or if they are empty, then all applications that match the specified ProductName will be returned. In the example below, all entries matching a 5722SS1 product will be returned (no extended data will be returned since the ExtendedData element is not present). The ComponentName attribute was specified as empty since it is required by the DTD.
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="5722SS1" ComponentName="" PackagedProduct="_">  </Component>
</RegAppInfoRepository>
```
When you specify the PackagedProduct attribute with a value of 1, it indicates that you want only information about IBM i packaged products. For example, if you specify the starts with selection criteria as shown in the following XML document, then all IBM i packaged product components with a ComponentName starting with 5 will be returned. Note that the ProductName attribute was defined because it is required by the DTD.
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="" ComponentName="5%" PackagedProduct="1">
  </Component>
</RegAppInfoRepository>
```

When you specify one of the allowed attributes or elements contained in the <ExtendedData> element and one of the attributes or elements is empty, it indicates that you want that data retrieved. For example, if you want to know the InstallerType for a component, you can specify the ExtendedData element as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="5722TC1" ComponentVersion="V5R3M0"
    ComponentName="5050" FeatureName="0000" PackagedProduct="1">
    <ExtendedData InstallerType="">
    </ExtendedData>
  </Component>
</RegAppInfoRepository>

When you specify one of the allowed attributes or elements contained in the <ExtendedData> element and it contains a value, it indicates that you want returned the component or components that have the attribute or element specified (depending on the selection criteria). For example, if you want to know all the components that were installed by ISJE:
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="" ComponentName="">
    <ExtendedData InstallerType="ISJE"> </ExtendedData>
  </Component>
</RegAppInfoRepository>
```

When you specify the ExtendedData element with no attributes or elements inside, it indicates that you want returned all available information for that component.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="5722TC1" ComponentVersion="V5R3M0"
             ComponentName="5050" FeatureName="0000"
             PackagedProduct="1">
       <ExtendedData/>
  </Component>
</RegAppInfoRepository>

Additional examples illustrating the way to define an XML document for input to this API follow:

List all information for all IBM i packaged products

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="" ComponentName="" PackagedProduct="1">
     <ExtendedData>
     </ExtendedData>
  </Component>
</RegAppInfoRepository>

List all IBM i packaged products with a product name ending in "TC1"

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="%TC1" ComponentName="" PackagedProduct="1"/>
</RegAppInfoRepository>

List all IBM i packaged products with "57" as the first two characters of the product name and "TC1" as the last three characters

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="57__TC1" ComponentName="" PackagedProduct="1"/>
</RegAppInfoRepository>

Notice in this example the use of the underline character. In this case we know the product name for IBM i packaged products is 7 characters long. The underline character should not be used if you do not know the number of characters in between.

List all available information for components containing the string "tool" in the component name

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="" ComponentName="%tool%">
     <ExtendedData></ExtendedData>
  </Component>
</RegAppInfoRepository>

List all supported IBM i packaged products

Having the following XML document, we can get the list of all supported IBM i packaged products.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="" ComponentName="" PackagedProduct="1">
    <ExtendedData Supported="1">
    </ExtendedData>
  </Component>
</RegAppInfoRepository>

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error addressing parameter list.
CPF3CF1 E	Error code parameter not valid.
CPF3CF2 E	Error(s) occurred during running of &1 API.
CPF9872 E	Program or service program &1 in library &2 ended.
CPF3C1E E	Required parameter &1 omitted.
CPF0CC1 E	Error initializing the XML parser.
CPF0CC2 E	Error found on XML input document.
CPF0CC7 E	Requested function not successful.
CPF0CD2 E	Application information path name not valid.
CPF0CDF E	Continuation handle not valid.

API introduced: V5R1

[ Back to top | Software Product APIs | APIs by category ]