Deletes a specific instance of a Grouping object type, all Comments instances attached to it, and all ATTACHMENT, CONTACT, CONTAIN, and LINK relationships in which it participates. Optionally also deletes all object instances contained in the Grouping category object instance, all Comments instances attached to them, and all ATTACHMENT, CONTACT, and LINK relationships in which they participate.
Authorization
Administrator or authorized user
Syntax
APIRET APIENTRY FLGDeleteTree( PSZ pszFLGID,
FLGOPTIONS Options,
PFLGHEADERAREA * ppListStruct,
PFLGEXTCODE pExtCode );
Parameters
Characters 1-6 of this ID identify the object type of this instance.
Characters 7-16 of this ID are the system-generated unique instance identifier.
This output structure contains the 16-character FLGID of each deleted object instance.
If this parameter is NULL, no output structure will be returned. If there is no output structure, then the pointer to the output structure is set to NULL.
See Appendix D, Information Catalog Manager reason codes for an explanation of the returned reason codes.
Usage
Prerequisite
The specified object instance ID (FLGID) must exist.
Restriction
Object instances that are contained by other Grouping objects than the one being deleted (as illustrated in Figure 59) are not deleted.
Freeing memory allocated for an output structure
If FLGDeleteTree returned data in the output structure, you must save the data returned in the output structure and then call FLGFreeMem (see FLGFreeMem). Do not use other methods, for example, C language instructions, to free memory.
Controlling updates to your information catalog
To keep your program as synchronized as possible with your information catalog, you should include a call to FLGCommit (see FLGCommit) after FLGDeleteTree completes successfully. If FLGDeleteTree does not complete successfully, you should include a call to FLGRollback (see FLGRollback).
Figure 58 through Figure 60 illustrate the effects of the two delete options. Figure 58 shows an information catalog with three grouping objects A, Z, and Y. Object B will be deleted using FLGDeleteTree.
Figure 58. Sample information catalog before deletions
Using the FLG_DELTREE_REL option, object instance B and some relationships under B are deleted. Object C and its containees are not touched because C is contained by another tree, Z. Object D is not contained by any other object and is therefore subject to the cascading effect.
Figure 59 illustrates the information catalog after B is deleted.
Figure 59. Example of the FLG_DELTREE_REL option
Using option FLG_DELTREE_ALL, object instance B and some instances under it are deleted from the catalog. Object instance C and its containees are kept, because it is also contained by Z.
Figure 60 shows the information catalog after B is deleted using the FLG_DELTREE_ALL option.
Figure 60. Example of the FLG_DELTREE_ALL option
Figure 61 shows the C language code required to issue the FLGDeleteTree call. This sample code deletes the DEPT001 Grouping category object instance, all Comments instances attached to it, and all ATTACHMENT, CONTACT, and LINK relationships in which it participates. The sample code also deletes all object instances contained in DEPT001 object instance, all Comments instances attached to them, and all ATTACHMENT, CONTACT, and LINK relationships in which they participate.
Figure 61. Sample C language call to FLGDeleteTree
APIRET rc; // Declare reason code
FLGOPTIONS ulOptMask=0;
UCHAR pszFLGID[FLG_ID_LEN + 1];
PFLGHEADERAREA pDelStruct=NULL;
FLGEXTCODE xc = 0; // Declare extended code
.
. set value for pszFLGID
.
ulOptMask = ulOptMask | FLG_DELTREE_ALL; // delete whole tree
rc = FLGDeleteTree (pszFLGID, ulOptMask,
&pDelStruct, &xc);
Figure 62 shows the output structure for the FLGDeleteTree call.
Figure 62. Sample output structure for FLGDeleteTree
