.\"##
.\" $XConsortium: p015,v 5.2 94/04/17 20:54:21 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 IDENTIFIER AND REFERENCES" 3P "29 February 1991"
.SH NAME
CHANGE STRUCTURE IDENTIFIER AND REFERENCES \- change the identifier assigned to a structure and all references to it
.IX "Structure Networks" "CHANGE STRUCTURE IDENTIFIER AND REFERENCES"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pchange_struct_id_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 Purpose
\s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 changes the identifier of
a specified structure and all references to the original identifier 
to the new identifier. References may be both \s-2EXECUTE STRUCTURE\s+2 elements and workstation postings.
.SS C Input Parameters
.IP \fIorig_struct_id \fP
Specifies the structure for which the identifier and references are to be changed.
.IP \fIresult_struct_id \fP
Specifies the new identifier to assign to the structure.
.SS Execution
The \s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 subroutine changes
the identifier associated with \fIorig_struct_id\fR to \fIresult_struct_id\fR.
This subroutine also changes all references to the original
structure identifier to instead refer to the resulting structure identifier.
The result of \s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 varies with the state of the original and resulting structures when the subroutine is called. The possible effects on the structures are described below.
.LP
Structure references are established by creating \s-2EXECUTE STRUCTURE\s+2
elements or by posting a structure. A single call to
\s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 changes both types
of references to the specified structure.
Details of how the subroutine changes each type of
structure reference are provided below.
.LP
If original structure identifier and resulting structure identifier specify the same structure, the subroutine does not take any action.
.sp
\fIThe Original Structure\fR
.LP
The structure identified by \fIorig_struct_id\fR will no
longer exist after this subroutine is executed, unless it was the open
structure. In this case, it continues to exist as the open structure after
the subroutine returns, but it will be empty and the element pointer
will be set to 0.
.sp
\fIThe Resulting Structure\fR
.LP
The resulting structure always exists at the end
of \s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2.
If \fIresult_struct_id\fR does not exist when the subroutine
is called, it is created and contains the elements of the original structure.
If \fIorig_struct_id\fR does not exist when the subroutine
is called, the resulting structure is empty.
.LP
If \fIresult_struct_id\fR already exists before \s-2CHANGE STRUCTURE
IDENTIFIER AND REFERENCES\s+2, the subroutine will replace its contents
with the contents of the original structure.
.LP
If the resulting structure is the open structure when the subroutine is called,
\s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 closes the structure,
replaces the contents with the elements from the original structure
and reopens the structure. The element pointer will be set to point to the last element.
.sp
\fIHow \s-2EXECUTE STRUCTURE\s+2 References are Changed\fR
.LP
\s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 changes all
\s-2EXECUTE STRUCTURE\s+2 elements throughout the Central Structure
Store that reference original structure identifier so that they reference
resulting structure identifier instead. Any references to \fIresult_struct_id\fR 
that already exist when \s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2
is called will not be changed by the subroutine.
.sp
\fIHow Posted Structures are Changed\fR
.LP
If \fIorig_struct_id\fR is posted to a workstation when
\s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 is called,
the subroutine unposts the original structure and posts
\fIresult_struct_id\fR with the same priority that the original
structure had.
.LP
If \fIresult_struct_id\fR is posted when
\s-2CHANGE STRUCTURE IDENTIFIER AND REFERENCES\s+2 is called,
it will remain posted and its priority will not change.
If \fIorig_struct_id\fR 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 REFERENCES (3P)"
.fi