Delete Registered Application Files (QSZDLTAF, QszDltRegAppFiles) API
Required Parameter Group:
1 | Application information path name | Input | Char(*) |
2 | Error code | I/O | Char(*) |
Service Program Name: QSZRAIRA
Default Public Authority: *EXCLUDE
Threadsafe: No
The Delete Registered Application Files (QSZDLTAF, QszDltRegAppFiles) API deletes the files listed in the Files tag for the given component. This API does not delete information from the IBM® i Registered Application Information Repository. To remove the Files tag from the repository, call the Update IBM i Registered Application Information Repository API.
This API can be used to generically uninstall simple applications that only need to remove the files that were installed and need no additional processing. It also can be used as a part of a more complex uninstall operation. This API can be called to remove an application's files after the uninstall operation has performed any unique processing (such as deleting a user profile).
Be aware of the following:
- This API should not be used for IBM i packaged products. The user should
use the Delete Licensed Program (DLTLICPGM) command to delete IBM i packaged
products. If a user chooses to use this API to delete objects for an IBM i
packaged product, an error will occur.
- The program calling this API should not be listed in the Files element of the component being processed; otherwise, lock contention may occur. If for some reason the program is listed, the program should be copied to a different location before calling this API.
Authorities and Locks
The authorities and locks for the first parameter are:
- 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
The authorities and locks for files to delete are:
Library Authority | *OBJEXIST |
Object Authority | *OBJEXIST |
Stream File Directory Authority | *OBJEXIST |
Stream File Object Authority | *OBJEXIST |
Required Parameter Group
- Application information path name
- INPUT; CHAR(*)
The path name of the object that contains a list of components whose files are to be deleted. 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 examples of how the XML input document may be structured, see XML document when deleting component files.
- 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 deleting component files
The XML document may be a stream file (*STMF) or a user space (*USRSPC) object. In either case, the XML document must conform to the Software components DTD.
Even though all elements defined in the data type definition (DTD) are allowed when using this API, only the RegAppInfoRepository and Component elements will be taken into account - the rest will be ignored. See Software components DTD for a detailed description of each element.
The components specified should match the information in the IBM i Registered Application Information Repository. For example, if a component was registered without specifying the ComponentVersion element, the ComponentVersion element should be omitted when using this API.
For each component tag in the XML document, the files for a single component will be deleted.
The examples below illustrate the way to define an XML document to call this API.
Delete files for a single component
<?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"> </Component> </RegAppInfoRepository>
Delete files for multiple components
Suppose you have two components which only differ in the component name (ComponentName attribute). The following example shows how files for the two components can be deleted.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd"> <RegAppInfoRepository DTDVersion="1.0"> <Component ProductName="XYZ" ComponentVersion="v3.1.0" ComponentName="Comp A" Instance="Unique" ComponentVendor="Juan Perez"> </Component> <Component ProductName="XYZ" ComponentVersion="v3.1.0" ComponentName="Comp B" Instance="Unique" ComponentVendor="Juan Perez"> </Component> </RegAppInfoRepository>
As you can see in the previous example, the difference between the two components is the ComponentName attribute. An error will occur if the document is given as follows:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE RegAppInfoRepository SYSTEM "/QIBM/XML/DTD/QszRegAppInfoRepository.dtd"> <RegAppInfoRepository DTDVersion="1.0"> <Component ProductName="XYZ" ComponentVersion="v3.1.0" ComponentName="" Instance="Unique" ComponentVendor="Juan Perez"> </Component> </RegAppInfoRepository>
Since the ComponentName attribute is empty, this matches two Component entries in the repository. In this case, the API will not know which files should be deleted, so an error will be returned.
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. |
CPF0CC3 E | Delete files not allowed for a packaged product. |
CPF0CC6 E | Not all components were successfully processed. |
CPF0CC7 E | Requested function not successful. |
CPF0CD2 E | Application information path name not valid. |
API introduced: V5R1