.\"##
.\" $XConsortium: p016,v 5.2 94/04/17 20:54:22 rws 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 "CHANGE STRUCTURE REFERENCES" 3P "29 February 1991"
.SH NAME
CHANGE STRUCTURE REFERENCES \- change all references to a specified structure to instead refer to another specified structure
.IX "Structure Networks" "CHANGE STRUCTURE REFERENCES"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pchange_struct_refs ( orig_struct_id, result_struct_id )
Pint	orig_struct_id;	\fIoriginal structure id\fP
Pint	result_struct_id;	\fIresult structure id\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purposer
\s-2CHANGE STRUCTURE REFERENCES\s+2 modifies the arrangement of the
structure network by changing all references to \fIorig_struct_id\fR 
to refer to \fIresult_struct_id\fR instead.
The subroutine changes both \s-2EXECUTE STRUCTURE\s+2 references and
any posting to a workstation.
.LP
The effect is to substitute the resulting structure for the original structure wherever it appears in a structure network or on a workstation posting.
.SS C Input Parameters
.IP \fIorig_struct_id\fP
\s-2CHANGE STRUCTURE REFERENCES\s+2 changes the references to this structure.
.IP \fIresult_struct_id\fP
Specifies the structure the original structure references will point to when \s-2CHANGE STRUCTURE REFERENCES\s+2 returns.
.SS Execution
The \s-2CHANGE STRUCTURE REFERENCES\s+2 subroutine changes
all references to the original structure identifier to refer
instead to the resulting structure identifier.
Structure references are established by creating
\s-2EXECUTE STRUCTURE\s+2 elements or by posting a structure.
A single call to \s-2CHANGE STRUCTURE REFERENCES\s+2 changes
both types of references to the specified structure.
The following details how the subroutine changes each
type of structure reference.
.sp
\fIHow \s-2EXECUTE STRUCTURE\s+2 References are Changed\fR
.LP
\s-2CHANGE STRUCTURE REFERENCES\s+2 changes all \s-2EXECUTE STRUCTURE\s+2
elements throughout the Central Structure Store that reference \fIorig_struct_id\fR
so that they reference \fIresult_struct_id\fR
instead. Any references to \fIresult_struct_id\fR that already
exist when \s-2CHANGE STRUCTURE REFERENCES\s+2 is called will not be
changed by the subroutine.
.LP
If the resulting structure does not exist when the subroutine is called,
it will be created as an empty structure and the original structure
references assigned to it.
.LP
If \fIorig_struct_id\fR and \fIresult_struct_id\fR 
specify the same structure, the subroutine does not take any action.
.sp
\fIHow Posted Structures are Changed\fR
.LP
If the original structure is posted to a workstation
when \s-2CHANGE STRUCTURE REFERENCES\s+2 is called, the subroutine
unposts it and posts the resulting structure
with the same priority that the original structure had.
.LP
If the resulting structure is posted when
\s-2CHANGE STRUCTURE REFERENCES\s+2 is called, it will remain
posted and its priority will not change.
If the original structure is also posted, it will be unposted.
.LP
Changes in a posted structure network are processed immediately and
may immediately affect the display.
The actual visual effects that appear on the display surface will
depend on the  workstation's current display update state.
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP\s+2, *, *, *)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "CHANGE STRUCTURE IDENTIFIER (3P)"
.SM "CHANGE STRUCTURE IDENTIFIER AND REFERENCES (3P)"
.fi