.\"##
.\" $XConsortium: p035,v 5.3 94/04/17 20:54:36 hersh Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "DELETE STRUCTURE NETWORK" 3P "29 February 1991"
.SH NAME
DELETE STRUCTURE NETWORK \- delete network of structures from central structure store
.IX "Structure Networks" "DELETE STRUCTURE NETWORK"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pdel_struct_net ( struct_id, ref_flag )
Pint	struct_id;	\fIstructure identifier\fP
Pref_flag	ref_flag;	\fIreference handling flag\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2DELETE STRUCTURE NETWORK\s+2 to remove from the Central Structure Store a specified structure and all structures referenced directly or indirectly by that structure.
.LP
A structure is referenced from within another structure by an \s-2EXECUTE STRUCTURE\s+2 element created by the \s-2EXECUTE STRUCTURE\s+2 subroutine. A structure network is a hierarchical arrangement of structures in which the original structure references subordinate structures which, in turn, reference other structures, and so on.
.LP
More than one \s-2EXECUTE STRUCTURE\s+2 element can refer to the same structure, so that a structure referenced in the network to be deleted can also be referenced by structures in other networks.
\s-2DELETE STRUCTURE NETWORK\s+2 includes a reference handling flag parameter which controls whether to delete or keep these structures.
.SS C Input Parameters
.IP \fIstruct_id\fP
Specifies the structure which is the beginning of the structure network to be deleted.
.IP \fIref_flag \fP
Controls how structures in the selected network that are also referenced by other structures outside the network are to be handled.  
This is an enumerated type defined in phigs.h as follows:
.sp
.ta .5i +1.25i
.nf
	PFLAG_DEL	\fIDelete all structures\fR
	PFLAG_KEEP	\fIKeep structures referenced outside the network\fR
.fi
.LP
The use of these values is described in the \fIExecution\fP section below.
.SS Execution
The \s-2DELETE STRUCTURE NETWORK\s+2 subroutine deletes the structure specified
by \fIstruct_id\fR and the structure network beginning with that structure.
The structure network is the chain of structures referenced by \s-2EXECUTE STRUCTURE\s+2
elements in \fIstruct_id\fR and its descendent structures.
.sp
If \fIstruct_id\fR does not exist, the subroutine takes no action and does not return an error.
.sp
The reference handling flag parameter controls how structures that are referenced both by this structure network and by another structure outside the network are handled.
.sp
.in .7i
.ta .5i
.ti -.2i
\(bu    If reference handling flag is \s-2PFLAG_DEL\s+2, \s-2DELETE STRUCTURE NETWORK\s+2
removes all structures referenced in the structure network beginning with 
structure identifier even if those structures are also referenced by 
another structure outside this network.
.sp .2
.ti -.2i
\(bu    If reference handling flag is \s-2PFLAG_KEEP\s+2, \s-2DELETE STRUCTURE NETWORK\s+2 
will \fBnot\fP remove structures referenced in this network which are 
also referenced by another structure outside this network. 
However, the structure specified by \fIstruct_id\fR identifier is always deleted.
.DT
.sp
.LP
All structures that are actually deleted are deleted as if
\s-2DELETE STRUCTURE\s+2 were called for each individual structure;
that is, the structure identifier,
its contents, and all references to it are removed.
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP, *, *, *\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "DELETE ALL STRUCTURES (3P)"
.SM "DELETE STRUCTURE (3P)"
.SM "DELETE STRUCTURE NETWORKS FROM ARCHIVE (3P)"
.fi