Update i5/OS Registered Application Information Repository (QSZUPDRA, QszUpdRegAppInfoRepository) API

The Update i5/OS Registered Application Information Repository (QSZUPDRA, QszUpdRegAppInfoRepository) API updates information about one or many separately installable pieces of an application called components. Each piece of information about each component is stored as a tag and a value. This API can be used to:

• Define a new component.
• Update a tag defined for a component.
• Add a new tag for the component.
• Remove a tag from the component.
• Remove a component and all its associated information (tags).

The flexibility of this API allows it to define all information for a component or a set of components in a single call since any number of components and tags may be specified in the same call.

It also can be used to remove a set of tags for a given component or it can even remove a set of components.

Be aware that this API should not be used to update information that belongs to i5/OS packaged products including the i5/OS Operating System. Information in the i5/OS Registered Application Information Repository is automatically updated by the system when a user installs an i5/OS packaged product using the Restore Licensed Program (RSTLICPGM) command or when the user deletes the product using the Delete Licensed Program (DLTLICPGM) command. If the user tries to update information for an i5/OS packaged product, an error will occur.

Authorities and Locks

Library Authority

*EXECUTE

Authority for user space containing XML document

*USE

User Space Lock

*EXCLRD

Stream File Directory Authority

*RX

Authority for Stream File containing XML document

*R

Required Parameter Group

Application information path name

INPUT; CHAR(*)

The path name of the object which contains the XML document with the information of the components to be updated by the API. This may be a path to a user space (*USRSPC) or a path to a stream file (*STMF). The path name must 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 should be given to the API as an XML document according to the data type definition (DTD). For a detailed description of the DTD, see "XML Document when updating".

Depending on the function requested, some of the tags may be optional. For example, to remove all information related to a specific component, you have to specify the remove function and only the component information; that is, product name, version, component name, instance, feature and vendor. The API removes the component from the repository along with its associated information.

Function

INPUT; BINARY(4)

The function to perform. The possible function values are:

1

The Add or Update function. The API adds or updates information in the i5/OS Registered Application Information Repository. The following actions may occur in the same call: If the component specified does not exist, the component and all the tag(s) associated with it are added. If the component already exists in the repository but its associated tags do not exist, the tags are added. If the component exists and its tags already exist, the tags are updated with their new values.

2

The Remove function. The API removes the tag or tags specified corresponding to the component from the i5/OS Registered Application Information Repository. If no tags are specified for the component, the component and all its associated information is removed.

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 updating

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 when using this API. See Software Components DTD for a detailed description of each element. The examples below illustrate the way to define an XML document to call this API.

Register only the component with no additional data.

When a component is being registered, use function add/update (1).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="My compiler" ComponentVersion="v1.1.0" ComponentName="Tools"
             ComponentVendor="Juan Perez" FeatureName="Juan Perez">
  </Component>
</RegAppInfoRepository>

Use one call to register and store all information related to a component.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd">
<RegAppInfoRepository DTDVersion="1.0">
  <Component ProductName="My tools" ComponentVersion="v1.1.0" ComponentName="Edit"
             Instance="/ProgramFiles/MyTools" ComponentVendor="Juan Perez">
    <ExtendedData UninstallInfo="java /ProgramFiles/MyTools/MyUninstaller"
       LastFixPackApplied="2.0" InstallerType="ISJE" Supported="0"
       Installed="1" CCSID="00037">
       <Shared>
          <SharingComponent ProductName="My compiler" ComponentVersion="v1.1.0"
                            ComponentName="EditTools" ComponentVendor="Pedro Fernandez"/>
       </Shared>
       <Files>
          <Directory DirectoryName="/ProgramFiles/MyTools/MyUninstaller/bin">
             <FileName>edit1.exe</FileName>
             <FileName>edit2.exe</FileName>
             <FileName>edit3.exe</FileName>
             <FileName>edit4.exe</FileName>
             <FileName>edit5.exe</FileName>
          </Directory>
       </Files>
       <AdditionalValue ValueName="InstallType" Value="Custom"/>
       <AdditionalValue ValueName="InstallDate" Value="05/10/1999"/>
    </ExtendedData>
  </Component>
</RegAppInfoRepository>

Error Messages