'\"macro stdmacro
.\"
.\" Copyright (c) 2016 Red Hat.
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMLOOKUPINDOMARCHIVE 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmLookupInDomArchive\f1 \- translate an instance name into an instance identifier
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
int pmLookupInDomArchive(pmInDom \fIindom\fP, const char *\fIname\fP);
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
.de CR
.ie t \f(CR\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
Provided the current
Performance Metrics Application Programming Interface (PMAPI)
context is associated with a set of archives,
.B pmLookupInDomArchive
will scan the union of all the instance domain metadata
for the instance domain
.IR indom ,
locate the first instance with the external identification given by
.IR name ,
and return the internal instance identifier.
.PP
This routine is a specialized version of the more general PMAPI
routine
.BR pmLookupInDom .
.PP
Only the leading
non-space characters of
.I name
will be used to identify the instance.
.PP
The value for the instance domain
.I indom
is typically extracted from a
.CR pmDesc
structure, following a call to
.BR pmLookupDesc (3)
for a particular performance metric.
.PP
.B pmLookupInDomArchive
will return a positive instance identifier on success.
.SH DIAGNOSTICS
.IP \f3PM_ERR_NOTARCHIVE\f1
the current PMAPI context is not associated with a set of archives
.IP \f3PM_ERR_INDOM_LOG\f1
.I indom
is not a defined instance domain identifier for the set of archives
.IP \f3PM_ERR_INST_LOG\f1
the external instance
.I name
is not known for the instance domain
.I indom
in the set of archives
.SH SEE ALSO
.BR PMAPI (3),
.BR pmGetConfig (3),
.BR pmGetInDomArchive (3),
.BR pmLookupDesc (3),
.BR pmLookupInDom (3),
.BR pmNameInDomArchive (3),
.BR pcp.conf (5)
and
.BR pcp.env (5).