.\"##
.\" $XConsortium: p014,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" 3P "29 February 1991"
.SH NAME
CHANGE STRUCTURE IDENTIFIER \-  change the identifier assigned to a structure
.IX "Structures" "CHANGE STRUCTURE IDENTIFIER"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pchange_struct_id ( 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
Use \s-2CHANGE STRUCTURE IDENTIFIER\s+2 to change the identifier of a specified structure.
.LP
Subroutines which create new structures, for example \s-2OPEN STRUCTURE\s+2 or \s-2EXECUTE STRUCTURE\s+2, include a parameter to assign an identifier for the newly created structure. The identifier is the number used to reference the structure in the Central Structure Store (CSS).
.SS C Input Parameters
.IP \fIorig_struct_id\fP
Specifies the structure for which the identifier is to be changed.
.IP \fIresult_struct_id\fP
Specifies the new identifier to assign to the structure.
.SS Execution
The \s-2CHANGE STRUCTURE IDENTIFIER\s+2 subroutine changes the identifier
associated with \fIorig_struct_id\fR to \fIresult_struct_id\fR.
The subroutine 
does not change any references that may exist in other structures to the original or the resulting structure. The result of \s-2CHANGE STRUCTURE IDENTIFIER\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.
.sp
\fIThe Original Structure\fR
.LP
If there are no references to the original structure
anywhere in the CSS,
\s-2CHANGE STRUCTURE IDENTIFIER\s+2 deletes the
original structure identifier from the CSS. If
there are references to the original structure, the original structure
continues to exist after the subroutine returns, but it will be
empty.
.LP
If original structure identifier is the open structure when
\s-2CHANGE STRUCTURE IDENTIFIER\s+2 is called, it continues to exist as
the open structure after the subroutine returns, but it will be empty.
The element pointer will be set to 0.
.LP
If the original structure is posted, it remains posted after \s-2CHANGE
STRUCTURE IDENTIFIER\s+2, but it remains as an empty structure. The display reflects the change in the posted structure according to the
workstation's display update state.
.sp
\fIThe Resulting Structure\fR
.LP
The resulting structure always exists at the end of \s-2CHANGE STRUCTURE IDENTIFIER\s+2. If the resulting structure identifier does not exist when the subroutine is called, it is created and contains the elements of the original structure. If the original structure identifier does not exist when the subroutine is called, the resulting structure is empty.
.LP
If the resulting structure identifier already exists before \s-2CHANGE STRUCTURE IDENTIFIER\s+2, the subroutine will replace its contents with the contents of 
the original structure identifier. Any existing references to the resulting 
structure identifier are not changed.
.LP
If the resulting structure identifier is the open structure when the subroutine is called, \s-2CHANGE STRUCTURE IDENTIFIER\s+2 closes the structure, replaces
the contents with the elements from original structure identifier, and reopens
the structure.  The element pointer will be set to point to the last element.
.LP
If the resulting structure identifier is posted when \s-2CHANGE STRUCTURE
IDENTIFIER\s+2 is called, it will remain posted after the subroutine is complete. The display is changed to reflect the new contents of the structure according to the display update state of the workstation to which the structure is posted.
.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 AND REFERENCES (3P)"
.SM "CHANGE STRUCTURE REFERENCES (3P)"
.fi