.\"##
.\" $XConsortium: p233,v 5.2 94/04/17 20:57:08 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 "LABEL" 3P "29 February 1991"
.SH NAME
LABEL \- create a structure element containing a label identifier
.IX "LABEL" "" "" "" PRINT "See Editing"
.IX "Elements" "LABEL"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
plabel ( label_id )
Pint	label_id;	\fIlabel identifier\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
The \s-2LABEL\s+2 subroutine puts a structure element containing a label identifier into the currently open structure. Labels are used to mark locations within a structure.
.LP
If the current edit mode is \s-2INSERT\s+2, the \s-2LABEL\s+2 element is inserted into the currently open structure after the element currently pointed to by the element pointer. If the edit mode is \s-2REPLACE\s+2, the \s-2LABEL\s+2 element replaces the element pointed to. In either case, the element pointer is updated to point to the new \s-2LABEL\s+2 element.
.SS C Input Parameter
.IP \fIlabel_id \fP
The label identifier is used by other subroutines to reference the label element's location in the structure.
.SS Execution
The \s-2LABEL\s+2 element is a marker within the structure. When the structure is traversed, \s-2LABEL\s+2 elements are ignored.
.sp
\s-2LABEL\s+2 elements are used by the \s-2SET ELEMENT POINTER AT
LABEL\s+2 and \s-2DELETE ELEMENTS BETWEEN LABELS\s+2 subroutines to
identify locations within a structure. The labels allow you to locate an
element or group of elements even if structure editing changes
the numbering of elements within the structure.
For example, you may wish to bracket a sequence of
related elements in a structure with labels.
.sp
Label identifiers need not be unique in a structure. The search for a
label within a structure is always from the element after the current
position of the element pointer toward the end of the structure.
Subroutines which refer to labels reference the next occurrence of the
specified label within the structure. If the specified label is not found
before the end of the structure, an error is generated.
.SH ERRORS
.IP 005
Ignoring function, function requires state (PHOP, *, STOP, *)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET ELEMENT POINTER AT LABEL (3P)"
.SM "DELETE ELEMENTS BETWEEN LABELS (3P)"
.SM "INQUIRE ELEMENT POINTER (3P)"
.SM "ELEMENT SEARCH (3P)"
.fi