.\"   $Id: addphins.3,v 1.1 2002/03/08 13:51:01 fred Exp $
.\" @(#)addphins.2 2.11 91/08/22 ; Labo masi cao-vlsi; Author : Frederic Petrot
.if t \{\
.XS \n%
.ti 0.2i
addphins
.XE
.XS0 \n%
.ti 0.2i
addphins
.XE0 \}
.TH ADDPHINS 3 "October 1, 1997" "ASIM/LIP6" "MBK PHYSICAL FUNCTIONS"
.SH NAME
addphins \- create a physical instance
.so jessie/alliance/alc_origin.1.en.gz
.SH SYNOPSYS
.nf
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
#include "mph.h"
phins_list \(**addphins(ptfig, figname, insname, sym, x, y)
phfig_list \(**ptfig;
char \(**figname;
char \(**insname;
char sym;
long x, y;
.ft R
.fi
.SH PARAMETERS
.TP 20
\fIptfig\fP
Pointer to the figure in which the instance should be added
.TP
\fIfigname\fP
Instance model name
.TP
\fIinsname\fP
Instance name
.TP
\fIsym\fP
Geometrical operation performed on the instance
.TP
\fIx, y\fP
Coordinates of the lower left corner of the instance
.SH DESCRIPTION
\fBaddphins\fP creates a new instance whose lower left corner is at the given
coordinates, and adds it to the
list of instances pointed to by \fIptfig\->PHINS\fP. The new instance is 
added in front of the list, and becomes itself the list head.
.br
The parameters \fIfigname\fP, \fIinsname\fP, \fIsym\fP, \fIx\fP and \fIy\fP
fill respectivly
the \fIFIGNAME\fP, \fIINSNAME\fP, \fITRANSF\fP, \fIXINS\fP and \fIYINS\fP
fields of the \fIphins\fP structure.
.br
The \fBaddphins\fP function does not check in memory or on disk to see
if the instanciated model exists, since no informations on it are needed.
.br
The coordinates are not transformation dependant. It means that the 
transformation is performed before placing the instance at the given point.
For details on the structure, see \fBphins\fR(3).
.SH RETURN VALUE
\fBaddphins\fP returns a pointer to the newly created instance.
.SH ERRORS
.LP
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
"\(**\(**\(** mbk error \(**\(**\(** addphins figure \fIfigname\fP cannot be part of itself"
.ft R
.RS
The instance has for model name of the figure on the which it is to be added.
It's illegal and dangerous. This check is made at the actual hierachy level
only, not recursivly on the structure, so it still may happend.
.RE
.LP
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
"\(**\(**\(** mbk error \(**\(**\(** illegal addphins transformation \fIsym\fP in : \fIinsname\fP"
.ft R
.RS
The geometrical operation is not in the legal range. See \fBphins\fP(3) for
a complete list of values.
.RE
.LP
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
"\(**\(**\(** mbk error \(**\(**\(** illegal addphins duplicate instance name : \fIinsname\fP"
.ft R
.RS
The instance name is an identifier, so it can't appear twice in the same figure.
.RE
.SH EXAMPLE
.ta 3n 6n 9n 12n 15n 18n 21n
.nf
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
#include "mph.h"
phins_list \(**ins_dup(pfd, pfs) /\(** duplicate instances \(**/
phfig_list \(**pfd, \(**pfs;
{
phins_list \(**pi;
	for (pi = pfs\->phins; pi != NULL; pi = pi\->NEXT)
		addphins(pfd, pi\->FIGNAME, pi\->INSNAME, pi\->TRANSF,
                         pi\->XINS, pi\->YINS);
	return pfd\->PHINS;
}
.ft R
.fi
.SH SEE ALSO
.BR mbk (1),
.BR phfig (3),
.BR phins (3),
.BR getphins (3),
.BR delphins (3).


.so jessie/alliance/alc_bug_report.1.en.gz