Pi data link-2017-sp1-user-guide-es-05

Function reference
PISampFilDat()
Returnsevenly-spaced,interpolatedandfilteredvaluesforaPI pointorPI AFattributestored
over a specified time period.
Syntax
Arguments
Argument Type Description
DataItem String The PI point name or PIAF attribute name for
whichthe function returnsvalues. Specify arange
of cells that contain PIpoint names or PIAF
attributenames toreturn values for each.
STime String The start of thetimeperiod for which the function
returns values.See Timeinputs.
ETime String The end of the timeperiod for whichthefunction
returns values.See Timeinputs.
Interval String The intervalbetween returned values.Enter a
v alue and timeunit that specifies the length of the
interval. For example, enter15m (15minutes) to
return avalue for every15-minute intervalduring
the timeperiod. SeeTime-intervalspecification.
FiltExp String A Boolean performanceequationthatthefunction
uses tofilter values. When the expression
ev aluates tofalse,the function excludes
correspondingvalues. See Filter expressions.
FiltCode Integer A code that indicateswhether tolabelfiltered
v alues:
• 1
Insert the labelFilteredin placeof avalueor
block of v alues that the function filtered from
the output based on FiltExp.
• 0
Do not label filtered values.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orientsoutput.SeeOutput codesfor information
on how tocomputethe code. This function
supports bits 1 and2.
RootPath String The path tothe data item. See Data items.
Examples
=PISampFilDat("sinusoid","11-Jan-1997","+3h","1h",A1,1,1,"")
Returns sampleddata forthePIpointsinusoid from thedefaultPI Data Archiveserver.The
functionretrievesvaluesatmidnight11-Jan-97,1:00a.m.on11-Jan-97,2:00a.m.on11-Jan-97,
PISampFilDat(DataItem, STime, ETime, Interval, FiltExp, FiltCode, OutCode,
RootPath)

Function reference
and 3:00 a.m. on 11-Jan-97. Iftheconditionin cellA1 is not satisfied atany ofthose times, the

Function reference
functionreturnsthelabelFiltered atthattime.Thefunctionshowstimestampsinthefirst
column and values in the secondcolumn.
See also
Sampled Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values
PIExpDat()
Returnsevenly-spaced,computedvaluesofaperformanceequationoveraspecifiedtime
period.
Syntax
PIExpDat(Expression, STime, ETime, Interval, OutCode, RootPath)
Arguments
Expression String One or more performance equations that the
function computesavaluefor.SeeExpressions.
Tospecify multipleexpressions, entera range of
cells that contain complete expressions. The
function returns values for each.
STime String The start of thetimeperiod for which the function
calculates a value. See Time inputs.
ETime String The end of the timeperiod for whichthefunction
calculates a value. See Time inputs.
Interval String The intervalbetween returned values.Enter a
v alue and timeunit that specifies the length of the
interval. For example, enter15m (15minutes) to
return avalue for every15-minute intervalduring
the timeperiod. SeeTime-intervalspecification.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orientsoutput.SeeOutput codesfor information
on how tocomputethe code. This function
supports bits 1 and2.
Examples
=PIExpDat("sqr('sinusoid')","y","t","1h",1,"thevax")
CalculatesthesquarerootofthevalueofthePIpointsinusoid retrievedfromthePIData
Archiveservernamedthevax atone-hourintervals,startingfrommidnightyesterdayto
midnight today.

Function reference
The function displays thetimestampforeachvaluein thecolumn to the left ofthecalculated
value.
See also
Sampled Data function
Interpolated values
PITimeDat()
Returns actualor interpolated samplevaluesofaPIpointorPI AF attributeatspecified time
stamps.
Syntax
PITimeDat(DataItem, TimeStamps, RootPath, Mode)
Arguments
DataItem String The PI point name or PIAF attribute name for which the
function returnsvalues. Specify arange of cells that contain
PI point namesor PIAF attribute names toreturnvalues for
each.
TimeStamps Reference A referencetoone or more worksheet cells that contain time
stamps for which the function returns values. See Time
inputs.
Mode String The method the function uses toretrieve data:
• interpolated
• exact time
Returns
Valuesat the specified time stamps, presented in the same orientation as the time stamp
reference. Ifthe time stamp referenceis arow,the functionpresentsvaluesin a row. Ifthetime
stamp referenceis a column, the function presentsvaluesin a column. The orientation ofthe
output array mustmatch the orientation ofthe timestampreference.
Examples
=PITimeDat("sinusoid",b1:b12,"","interpolated")
Retrieves interpolatedvalues at the time stamps locatedin cells B1 through B12 forthe PI
point sinusoid on the default PI Data Archive server.
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.
See also
Timed Data function

Function reference
Interpolated values
PITimeExpDat()
Returns values ofa performance equation calculated at specified time stamps.
Syntax
PITimeExpDat(Expression, TimeStamps, RootPath)
Arguments
Expression String One or more performance equations that the
function computesavaluefor.SeeExpressions.
Tospecify multipleexpressions, entera range of
cells that contain complete expressions. The
function returns values for each.
TimeStamps Reference A referencetoone or more worksheet cells that
containtimestampsfor which thefunction returns
v alues. See Time inputs.
Returns
Valuesat the specified time stamps, presented in the same orientation as the time stamp
reference. Ifthe time stamp referenceis arow,the functionpresentsvaluesin a row. Ifthetime
stamp referenceis a column, the function presentsvaluesin a column. The orientation ofthe
output array mustmatch the orientation ofthe timestampreference.
Examples
=PITimeExpDat("sqr('sinusoid')",b1:b12,"")
CalculatesthesquarerootofthevalueofthePIpointsinusoid retrievedfromthedefaultPI
Data Archive server at the times specified in cells B1 through B12.
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.
See also
Timed Data function
Calculation functions
CalculationfunctionscomputevaluesfromPIpointvalues,PIAFattributes,orperformance
equation evaluations during a specific time period.

Function reference
Topics in this section
• PIAdvCalcVal()
• PIAdvCalcFilVal()
• PIAdvCalcExpVal()
• PIAdvCalcExpFilVal()
• PIAdvCalcDat()
• PIAdvCalcFilDat()
• PIAdvCalcExpDat()
• PIAdvCalcExpFilDat()
• PITimeFilter()
• PITimeFilterVal()
PIAdvCalcVal()
ReturnsavaluecalculatedfromPI pointorPIAFattributevaluesduringaspecified time
period. This function supports bulkcalls.
Syntax
Arguments
function calculates a value. Specify a range of cells that
containPIpointnames orPIAF attribute names tocalculatea
v alue for each.
STime String The start of the time period for which thefunction calculates
a v alue.See Timeinputs.
ETime String The end of the timeperiod for whichthe function calculates a
v alue.See Time inputs.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
PIAdvCalcVal(DataItem, STime, ETime, Mode, CalcBasis, MinPctGood, CFactor,
OutCode, RootPath)

Function reference
MinPctGood Number The minimumpercentageof good datarequiredduringthe
time period tocalculate and return a value.
CFactor Number A factor that the function applies tothereturnedvalue. Enter
1if a conversion factor is not needed. For time-weightedtotal
calculations,specify a factor that converts recorded rate
v alues tothe server default time unit (units per day).
OutCode Integer An output code that determines what appended data the
function returns and how thefunction orientsoutput. See
Outputcodes for information on how tocomputethecode.
This function supports bits 2,3,and 9 (if Mode is set to
minimum, maximum, or range).
Examples
=PIAdvCalcVal("sinusoid","y","t","total","time-weighted",50,1,4,"")
Returnsatime-weightedtotalofthePIpointsinusoidcalculatedfromthevaluesonthe
default PI Data Archiveserverfrom yesterday to today.
The function multiplies the resultby 1,and only returns aresultifat least 50 percent ofthe
data is good.The function returns the percent good to theright ofthe calculated total.
See also
Calculated Data function
Retrieval oflarge amounts ofdata
PIAdvCalcFilVal()
ReturnsavaluecalculatedfromfilteredPIpointorPI AFattributevaluesduringaspecified
time period.
Syntax
Arguments
function calculates a value. Specify a range of cells that
containPIpointnames orPIAF attribute names tocalculatea
v alue for each.
PIAdvCalcFilVal(DataItem, STime, ETime, FiltExp, Mode, CalcBasis, SampMode,
SampFreq, MinPctGood, CFactor, OutCode, RootPath)

Function reference
FiltExp String A Boolean performanceequation thatthefunction usesto
filter values. When the expression evaluates tofalse, the
function excludes corresponding values.See Filter
expressions.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
SampMode String The samplingmethod thefunction uses todetermine when to
ev aluate FiltExp:
• compressed
• interpolated
SampFreq String The frequency that the function evaluates FiltExp if
SampMode isset tointerpolated.Enter avalueandtime
unit. For example,set to10m (1 0 minutes)toreturn an
interpolatedvaluefor every10-minuteinterval. See Time-
interval specification
Examples
Returnsthetime-weightedtotalforthePIpointsinusoidcalculatedfromthevaluesonthe
default PI Data Archive server, summing values from yesterday to today during the time
periods when thePI pointcdm158 is set to Manual.
The function multiplies the result by 1. Because the sampling mode is compressed, the
functionignoresthesamplingfrequencyandsamplesthefilterexpressionatthecompressed
=PIAdvCalcFilVal("sinusoid","y","t","'cdm158'=""Manual""","total","time-
weighted","compressed","10m",50,1,4,"")

Function reference
events ofthe point sinusoid.Thefunction only returns a resultifatleast 50 percentofthe
data is good.The function returns the percent good to theright ofthe calculated total.
See also
Filter expressions
Interpolated values
PIAdvCalcExpVal()
Returns a value calculated from a performance equation during a specified time period.
Syntax
Arguments
Expression String Oneor moreperformanceequations thatthe function
computes a valuefor. SeeExpressions.
Tospecify multipleexpressions, enter a range of cells that
containcompleteexpressions.Thefunction returnsvaluesfor
each.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
SampMode String The sampling method thefunction uses todetermine when to
ev aluate Expression:
• compressed
• interpolated
PIAdvCalcExpVal(Expression, STime, ETime, Mode, CalcBasis, SampMode, SampFreq,
MinPctGood, CFactor, OutCode, RootPath)

Function reference
SampFreq String Thefrequencythat thefunction evaluatesExpressionif
SampMode is set to interpolated. Enter a value and time
interpolatedvalueforevery10-minuteinterval.SeeTime-
RootPath String The path tothe data itemreferenced by the expression. See
Data items.
Examples
Returns the time-weighted total for the expression 'sinusoid'+'cdt158' calculated from
the values on the default PI Data Archive server,using values from yesterday to today.
function ignores the sampling frequencyand samples the filter expression at the combined
compressedeventsofsinusoid and cdt158.Thefunctiononly returns aresult ifatleast50
percentofthe data is good. Thefunction returns the percentgood to the rightofthe calculated
total.
See also
Interpolated values
PIAdvCalcExpFilVal()
Returns a filtered, calculated PI point value basedon a performanceequation.
Syntax
=PIAdvCalcExpVal("'sinusoid'+'cdt158'","y","t","total","time-
PIAdvCalcExpFilVal(Expression, STime, ETime, FiltExp, Mode, CalcBasis, SampMode,

Function reference
Arguments
each.
expressions.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
ev aluate Expressionand FiltExp:
• compressed
• interpolated
SampFreq String Thefrequencythatthefunction evaluatesExpressionand
FiltExp if SampMode is set to interpolated. Enter a value
and timeunit. For example, set to10m (10minutes)toreturn
an interpolatedvaluefor every10-minuteinterval. SeeTime-
interval specification.
v alues totheserver default time unit (units per day).

Function reference
Data items.
Examples
Returns the time-weighted total for the expression 'sinusoid'+'sinusoidu' calculated
from the values on the default PI Data Archive serverwhen the PIpoint cdm158 issetto
Manual using values from yesterday to today.
function ignores the sampling frequencyand samplesthefilter expression atthecombined
compressedeventsofsinusoidandsinusoidu.Thefunctiononlyreturnsaresultifatleast
50 percent ofthe data is good. The function returns the percent good to the right ofthe
calculated total.
See also
Filter expressions
Interpolated values
PIAdvCalcDat()
ReturnsevenlyspacedvaluescalculatedfromPI pointorPI AFattributevaluesduringa
specified time period.
Syntax
Arguments
function calculates values. Specify a range of cells that
containPIpointnamesor PIAFattributenamestocalculate
v alues for each.
ETime String The endof thetimeperiod for which the function calculates
=PIAdvCalcExpFilVal("'sinusoid'+'sinusoidu'","y","t","'cdm158'=""Manual""","total
","time-weighted","compressed","10m",50,1,4,"")
PIAdvCalcDat(DataItem, STime, ETime, Interval, Mode, CalcBasis, MinPctGood,
CFactor, OutCode, RootPath)

Function reference
150 PI DataLink 2017SP1 User Guide
Interval String The intervalbetween returnedvalues. Enter avalueand time
unit that specifies the length of the interval. For example,
enter 15m (15minutes) toreturn avalue for every15-minute
interval during the time period. See Time-interval
specification.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
Outputcodes forinformation on how tocompute thecode.
This function supports bits 2,3,7,8,and9 (if Mode is set to
Examples
=PIAdvCalcDat("sinusoid","y","t","3h","total","time-weighted",50, 1,4,"")
Returnsthetime-weightedtotalforthePIpointsinusoidcalculatedfromthevaluesonthe
defaultPI DataArchiveserverforthree-hourintervalsfrommidnightyesterdaytomidnight
today.
The function multiplies the resultby 1,and only returns aresultifat least 50 percent ofthe
data is good.The function returns thepercent good to theright ofeach calculated total.
See also

Function reference
PIDataLink2017SP1UserGuide 151
PIAdvCalcFilDat()
ReturnsevenlyspacedvaluescalculatedfromfilteredPIpointorPIAFattributevaluesduring
a specified time period.
Syntax
Arguments
function calculates values. Specify a range of cells that
containPIpointnamesor PIAFattributenames tocalculate
v alues for each.
specification.
expressions.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
ev aluate FiltExp:
• compressed
• interpolated
PIAdvCalcFilDat(DataItem, STime, ETime, Interval, FiltExp, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)

Function reference
SampFreq String The frequency that the function evaluates FiltExp if
SampMode isset tointerpolated.Enter avalueandtime
interpolatedvaluefor every10-minuteinterval. See Time-
Examples
Returnsthetime-weightedtotalforthePIpointsinusoid,calculatedfromthevaluesonthe
defaultPI DataArchiveserverforthree-hourintervalsfrommidnightyesterdayto midnight
today when PI pointcdm158 is set to Manual.
function ignores the sampling frequencyandsamples thefilterexpression at the compressed
events ofsinusoid.The function only returnsa result ifat least50 percentofthedata isgood.
The function returns thepercentgood to the right ofthe calculated total.
See also
Filter expressions
Interpolated values
PIAdvCalcExpDat()
Returnsevenlyspacedvaluescalculatedfromaperformanceequationduringaspecifiedtime
period.
Syntax
=PIAdvCalcFilDat("sinusoid","y","t","3h","'cdm158'=""Manual""","total","time-
PIAdvCalcExpDat(Expression, STime, ETime, Interval, Mode, CalcBasis,SampMode,

Function reference
Arguments
each.
specification.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
ev aluate Expression:
• compressed
• interpolated
SampFreq String Thefrequencythat thefunction evaluatesExpressionif
SampMode is set to interpolated. Enter a value and time
interpolatedvalueforevery10-minuteinterval. SeeTime-

Function reference
Data items.
Examples
Computestheexpression'sinusoid'+'cdt158'atanytimestampbetweenmidnight
yesterdayand midnighttodaywitha recordedvaluestored on thedefaultPIData Archive
server,and then calculates thetime-weighted total ofthecomputedvalues in three-hour
intervals.
The function multiplieseachcalculated total by 1 andreturns avalue when the percentofgood
values is atleast 50 percent during thethree-hourinterval.The function returns the percent
goodto therightofthecalculatedtotal.Notethatbecausethesamplingmodeiscompressed,
the function ignores the sampling frequency, and samples values whenever sinusoid or
cdt158has a recorded value stored.
See also
Interpolated values
PIAdvCalcExpFilDat()
Returnsevenlyspacedvaluescalculatedfromafilteredperformanceequationduringa
specified time period.
Syntax
Arguments
each.
=PIAdvCalcExpDat("'sinusoid'+'cdt158'","y","t","3h","total","time-
PIAdvCalcExpFilDat(Expression, STime, ETime, Interval, FiltExp, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)

Function reference
specification.
expressions.
• total
• minimum
• maximum
• stdev
• range
• count
• time-weighted
• event-weighted
SampMode String The samplingmethod thefunction uses todetermine when to
ev aluate Expressionand FiltExp:
• compressed
• interpolated
SampFreq String Thefrequencythatthefunction evaluatesExpressionand
FiltExp if SampMode is set to interpolated. Enter a value
and timeunit. For example, set to10m (10minutes)toreturn
an interpolatedvaluefor every10-minuteinterval. SeeTime-
interval specification.
Data items.

Function reference
Examples
Calculates a time-weighted total for the expression 'sinusoid'+'cdt158' when 'cdm158'
= "Manual" atthree-hourintervalsfromyesterdaytotodayfromthedefaultPIDataArchive
server.
The function multiplieseachcalculated total by 1 andreturns avalue when the percentofgood
values is atleast 50 percent during thethree-hourinterval.The function returns the percent
goodto therightofthecalculatedtotal.Notethatbecausethesamplingmodeiscompressed,
the function ignores the sampling frequency, and samples values whenever sinusoid or
cdt158 has a recorded valueorthe valueofcdm158 changesto or from Manual.
See also
Filter expressions
Interpolated values
PITimeFilter()
Returnstheamountoftimethataperformanceequationevaluatesto true duringevenly
spaced intervals in a specifiedtime period.
Syntax
PITimeFilter(Expression, STime, ETime, Interval, TimeUnit, OutCode, RootPath)
Arguments
Expression String A Boolean performanceequationthat thefunctionevaluates.
See Expressions.
Reference arange of cells that containexpressions toreturn
v alues for each.
specification.
=PIAdvCalcExpFilDat("'sinusoid'+'cdt158'","y","t","3h","'cdm158'=""Manual""","tot
al","time-weighted","compressed","10m",50,1,4,"")

Function reference
TimeUnit String Time unit of the calculated result:
• seconds
• minutes
• hours
• days
This function supports bits 2,3,7,and 8.
Data items.
Examples
=PITimeFilter($A$1,"y","t","1h","seconds",65,"thevax")
Returns the number ofseconds that the expression in cell A1 is true on the PI Data Archive
servernamedthevaxduringone-hourintervals,startingfrommidnightyesterdayto midnight
today.
The function showsthetimestamp ofthestartofeach calculation interval to the left ofthe
value.
See also
Time Filtered function
PITimeFilterVal()
Returnstheamountoftimethataperformanceequationevaluatestotrue duringaspecified
time period.
Syntax
PITimeFilterVal(Expression, STime, ETime, TimeUnit, OutCode, RootPath)
Arguments
Expression String A Boolean performanceequationthat thefunctionevaluates.
See Expressions.
Reference arange of cells that containexpressions toreturn
v alues for each.

Function reference
TimeUnit String Time unit of the calculated result:
• seconds
• minutes
• hours
• days
This function supports bits 2 and 3.
Data items.
Examples
=PITimeFilterVal($A$1,"y","t","seconds",0,"thevax")
Returns the number ofseconds that theexpression in cellA1 is true on the PI Data Archive
servernamedthevax from midnightyesterday to midnighttoday.
See also
Time Filtered function
Tag functions
Tag functions help you work with PI points.
• PIPointIDToTag()
• PIAttributeMaskToTag()
PIPointIDToTag()
Returns the name ofthe PI point that corresponds to a specific PI point ID.
Syntax
PIPointIDToTag(PointID, Server)
Arguments
PointID String A PIpoint ID,which is auniqueinternalID that is not reused
when a point is deleted.

Function reference
Server String The PI Data Archive server that thefunction returns data
from. Ifyou donot select a serveror leave thefield blank, the
function searches thedefault PIData Archiveserver.
Examples
=PIPointIDToTag("123","thevax")
SearchesthePIDataArchiveservernamedthevax forpointID123,andreturnsthatpoint's
name (the Tag attribute).
See also
PointIDto Tagfunction
PIAttributeMaskToTag ()
Returns the names ofPI points that match oneor morespecified PI point attribute values.
Syntax
Arguments
TagName String Name of returned points.1
Descriptor String Descriptor of returned points.1
PointSource String Point source of returned points.1
PointType String Point type of returned points.1
PointClass String Point class of returnedpoints.1
EngUnits String Engineering units of returned points.1
OutCode Integer An output code that determines how thefunction orients
output:
• 0
Write values in a column.
• 2
Write values in a row.
1 Use wildcard character (*)tofind allmatches or matches limited tospecified characters.
Examples
=PIAttributeMaskToTag("sin*","*","*","*","*","*",0,"thevax")
PIAttributeMaskToTag(TagName, Descriptor, PointSource, PointType, PointClass,
EngUnits, OutCode, Server)

Function reference
Returns the names ofpoints that start with sin from the PI Data Archive server named
thevax.
See also
Attribute Mask to Tag function
Module Databasefunctions
• PIAliasToTag()
• PIPropertyToValue()
PIAliasToTag()
Returns the name ofthe PI point that corresponds to a specified PI alias.
Syntax
PIAliasToTag(Alias, ModulePath, QueryDate, OutCode, Server)
Arguments
Alias String The module databasealias that corresponds tothe PIpointto
return.
ModulePath String The full module path tothe alias
QueryDate Integer An effective dateof the alias.Thefunction returns the name
of the point that corresponds tothe specified alias on this
date.
OutCode Integer An output code thatdetermines whether toappend the
serv er name totheresult:
• 0
Returns only point name.
• 1
Returns the PIData Archiveserver thatstores thepoint in
the celltothe right of thepoint name.
• 2
Returns the PIData Archiveserver thatstores thepoint in
the cell below the pointname.
Examples
=PIAliasToTag("Temperature","Unit1Reactor1","*",0,"thevax")

Function reference
Returns the name ofthe PI point that corresponds to the Temperature alias of module
Reactor1,whichisasubmoduleofUnit1.Unit1 isattherootofthemoduledatabaseforaPI
Data Archiveserver namedthevax. The module database is queried atthecurrenttime.
See also
Alias to Tag function
PIPropertyToValue()
Returns the value or values corresponding to a specified PI property.
Syntax
PIPropertyToValue(Property, ModulePath, QueryDate, Server, OutCode)
Arguments
Property String The module databaseproperty that corresponds tothe PI
point for which the function retrievesvalues.
ModulePath String The full module path tothe property.
QueryDate Integer An effectivedate of the PIproperty value.Thefunction
returns thevaluesthat correspondtothespecifiedproperty
on this date.
OutCode Integer An output code that determines how toorient the result:
• 0
Returns values in a column.
• 2
Returns values in a row.
Examples
=PIPropertyToValue("Implementer","Unit1Reactor1","*","thevax")
ReturnsthevaluecorrespondingtotheImplementerpropertyofmoduleReactor1whichisa
submoduleofUnit1.Unit1 is at the rootofthemodule database for aPI Data Archive server
named thevax. The module database is queried at thecurrent time.
See also
Property to Valuefunction
Input functions
Input functions writevalues to PI Data Archive or PI AF.

Function reference
PIPutVal() and PIPutValX()
Writes a valueto the PI Data ArchiveserverorPI AF serverandreturns astring thatindicates
the status.
Syntax
PIPutVal(DataItem, Value, TimeStamp, RootPath, OutCell)
PIPutValX(DataItem, Value, TimeStamp, RootPath, OutCell)
Arguments
DataItem String The nameof the PIpoint or PIAF attributetowhichthe
function writes a value.
Value Reference A referencetothe cell that contains thevaluetobewritten,
either a string or a number.
TimeStamp String The time stamp for the value.See Time inputs.
OutCell Reference A referencetothecellwherePIDataLinkwrites thestring
that macrofunction returns. The returned stringvaries:
• If the write succeeds:
◦ ThePIPutValfunction returnsxxx Written where
xxx is either Real Value, Integer, Digital State,
or Value, depending on the v alue ty pe written.
◦ The PIPutValXfunction returns Value Written.
• If the write fails, the function returns an error code such
as [-5] Tag not found.
Notes
The PIPutVal and PIPutValX functions cannotwrite to PI AF attributes that are
configuration attributes. These functions can only writeto a PI AF attribute for which the
Configuration Item checkboxisnotselected.Youcancheckthestatusofthecheckboxonthe
Attributes tab in PI System Explorer.
The PIPutVal and PIPutValX functions support all PI Data Archive data types. The functions
interprettimestampsusingclient-machinetime-zoneinformationforPI DataArchiveunless
the PI Data Archive time zone setting is enabled.
Note:
(VBA). Do not enter these functions in theExcel formula bar. See Functions to write
data.
In the currentversion ofPIDataLink, there is no differencebetween thePIPutVal
2013, the PIPutVal function only supported threetraditional PI point types:real,
integer,anddigital.InthoseversionsofPIDataLink,thePIPutValX functionadded
support for string points and subsecondtime stamps.

Function reference
The functionsdo notverify the user-specified rangefora point beforewritingthevalue. The
range is definedas zero to zero + span,wherezero and span arepointattributes specified
duringpointcreation.ThefunctionreturnsaValue Written stringevenifOver Rangeor
Under Range is stored in PI Data Archive.
Deprecated functions
Several functions havebeenreplacedby morepowerful functions. To supportolder worksheets
that use these replaced functions, PI DataLink supports the old, deprecatedfunctions, but
OSIsoft recommends that you use thecorresponding new functions.
Old function New function
PICalcVal PIAdvCalcVal
PICalcDat PIAdvCalcDat
PIExTimeVal PIArcVal (with Mode set toexact time)

Function reference

Troubleshooting
ConsultthetopicsinthissectionifyouexperiencedifficultyusingPI DataLink.Ifthesetopics
do notaddressorsolvetheproblem,contactTechnicalSupport(seetheOSIsoftTechSupport
Contact Us page (https://techsupport.osisoft.com/Contact-Us/)).
• Log files
• PI DataLink tab notavailable
• Arrayandcelllimits
• Data retrieval limits
• Data item not supported by function
• Duplicate event exists
• Security
• PI Data Archive connection issues
• Eliminate timeout exception error
• Data does not update
Log files
PI DataLink does not generatea generic log file.You can useerrormessagesin worksheetsto
diagnose issues. However,some specific processes do generate log files:
• Installation
The ../pipc/dat directory contains the installation log files, SetupPIDataLink_x64.log
and SetupPIDataLink_x86.log.
• PI Data Archiveserverconnectivity
Examine the PI Data Archive logfile inPI SMT for PIData Archiveserverconnectivity issues.
PI DataLink tab not available
If the PI DataLink tab does not appear after you install PI DataLink, you might need to
manually configuretheadd-inforExcel(seeMicrosoftExceladd-inconfiguration),orreduce
security settings for add-ins (seeSecurity).
Someuser-writtenVBA scriptsinExcelworksheets(oradd-ins)resetthemainExcelribbon.In
such cases, the PI DataLink tab might disappear even though the PI DataLink add-in is still
loaded,andembeddedPI DataLinkfunctionsmayworkeventhoughthePIDataLinktabitself
is not available. Restarting Excel usually fixes this problem.

Troubleshooting
Array and cell limits
PIDataLink issubjecttoanExcellimitation onthenumberofelementsinacalculation array.A
single PI DataLink function can return no morethan 1,048,576values per retrieval.
TheExcelSDK usedby PI DataLinklimitsstringsto 255charactersinlength.Inputstringsfor
PI DataLink expressions in a referenced cell may not exceed this255-character limit.
Similarly,PI DataLink might truncate string output,such as PI point names, to 255 characters.
Data retrieval limits
Errorcode-11091indicatesthatasinglequeryinitiatedbyaPI DataLinkfunctionattempted
to retrievemorerecordedvaluesfromPIDataArchivethanallowedbytheArcMaxCollect
tuning parameter.
Because this limit applies to recordedvalues retrieved from PI Data Archive, even functions
that return small numbers ofvalues can exceedthelimitposed by this tuning parameter.For
example,thevalue ofthe PIpoint sinusoid constantlyvariesbetween0 and100.You might
create afunction thatreturnssampledvalues ofsinusoid every 30 seconds over ayearwitha
filter to exclude values less than 95. This function might return a relatively small number of
values, but will retrieve many morerecorded values from thearchives to process the query.
Ifyou receivethis error,considermodifying yoursearch criteria to reducethe dataretrieved.
For example,youmightreducethetime period overwhich the function retrievesdata.
Data item not supported by function
The returned message Data item not supported by function can indicate:
• A PI AF attributeuses acustomdata reference thatdoesnot allow calculations. To use in PI
DataLink, change thecustom-data-referencecodeto permituseofdata-access methods.
This is disabled by default.
• TheCalculatedDatafunctionattemptedasummarycalculationonaPI AFattributeoftype
PI Point Array.
Duplicate eventexists
ThereturnedmessageDuplicate event exists: specify index for EventName
indicates that the parent event in this worksheetrow contains morethan one child event
namedEventName.Toresolve,changethespecificationoftheCompareEventsfunctiontouse
an indexed version oftheevent for theattributedisplayed in this column.
When aparenteventhaschildeventswithduplicatenames,PI DataLinkautomaticallyaddsan
index to thechild event name in theAddAttributes window.Ifothereventsat the samelevel do
not haveduplicate names, they will nothave the index. Formore details,seeAddchild-event
attributesas columnsin the Compare Events task pane.

Troubleshooting
Security
Excel security featuresforadd-ins,ActiveXcontrols,and macroscontrolthetypes of
componentsthat canrun insideExcel.Thesecuritysettingseitherdisable,enablewith
prompting,or completely enablethesetypes ofobjects.
Excel security settings may conflict with certain PI DataLink features:
• PI DataLinkisanExceladd-in.Securitysettingsthatdisableadd-inspreventPIDataLink
from loading in Excel.
• TrendsuseasignedActiveXcontrolmarkedsafeforinitializationandrequirethatActiveX
controls be enabled.
• WorksheetsthatcontainaPIPutVal()orPIPutValX ()functionusemacrosandrequire
that macrosbe enabled (seePIPutVal() and PIPutValX()).
If you regularly apply Excel security to worksheets, or encounter problems using these PI
DataLink features,youmayneedtoreduceoreliminateExcelsecuritysettingsdependingon
how you plan to usePI DataLink.
ForfurtherinformationonExcelsecurity,consultMicrosoftExcelonlinehelpandonline
resources.
PI Data Archive connection issues
ThisversionofPIDataLinkusestightersecuritysettingsforconnectingtoPIDataArchive.The
new settings reduceexposure to security weaknesses associated with PI password
authentication.Formoreinformation,seetheOSIsoftTechSupportalert,AL00206-Security
Alert: PI Authentication Weakness (https://techsupport.osisoft.com/Troubleshooting/Alerts/
AL00206).
The new security settings can result in errors ifPI DataLink uses:
• PI user names and passwords to connect to PI Data Archive
• Default user to connectto PI Data Archive
Specifically, these settings might generate the following error:
Cannot connect to the PI Data Archive. Windows authentication trial
failed because insufficient privilege to access the PI Data Archive.
Trust authentication trial failed because insufficient privilege to
access the PI Data Archive.
To resolve these errors,you can:
• Configure PI mappings for userswho connect to PI Data Archive.
OSIsoftrecommendsthisapproach(availableinPI DataArchiveversion3.4.380andlater).
This is the mostsecure connection method. For informationoncreating PI mappings, see
the PI Server topic "Mapping management" in Live Library (https://livelibrary.osisoft.com).
To usePImappings,youmustalsoenabletheWindowsSecurityauthenticationprotocolon
each computerthat runs PI DataLink.
• Configure PI trusts for userswho connect to PI Data Archive.

Troubleshooting
This is the next-bestapproach. To use PI trusts,youmust also enable thePI Trust
authentication protocol on each computerthatruns PI DataLink.
• Configure each computerto allow anexplicitlogin prompt whena PI mappingor PI trust is
not available.
OSIsoft does not recommend this approach. Explicit logins are not secure. With this
approach,you must enteryouruser name and password thefirst timeyou connect to each
PI Data Archive during a particularMicrosoft Excel session.
Formoreinformation,seethePIServertopic"Manageauthentication"inLiveLibrary(https://
livelibrary.osisoft.com).
• Enable an authentication protocol
• Configure a computerto allow explicit login prompts
• Enter login credentials from Connection Manager
Enable an authentication protocol
To connecttoPI DataArchivewithadefinedPImappingorPItrust,usePI SDKUtility to enable
the corresponding protocolonyourcomputer.Youmust configure each computer where you
connectto PI Data Archivewith a PI mapping orPI trust.
Procedure
1. Click Start> All Programs > PI System > PISDKUtility to open PI SDK Utility.
2. Under PI-SDK, click Connections to show available PI Data Archive servers and update the
utility menus.
3. Click Connections > Options to open the ConnectionOptions window.
4. Under Specify Authentication Procedure, use the arrow keys to move and sort the enabled
protocols listed underProtocol order. List the needed protocols:
◦ TousePI mappings,WindowsSecuritymustbelisted.Thisshouldbethefirstprotocolin
the Protocol order list.
◦ To use PI trusts, PI Trust must be listed.
5. Click OK.
Configure a computer to allow explicit login prompts
To connectto PIData Archiveby logging in as aPI user,use PISDK Utility to configureyour
computerto allowexplicitloginprompts.Youmust configureeachcomputer whereyouwant
to connect to PI Data Archiveby logging in as a PI user.
Note:
Entering an incorrect password ata login promptcan result in the same error message.
Caution:
OSIsoftrecommendsthatyouselectanalternative,moresecuremethodtoconnecttoPI
Data Archive.

Troubleshooting
Procedure
1. Click Start> All Programs > PI System > PISDKUtility to open PI SDK Utility.
2. Click Connections > Options to open the ConnectionOptions window.
3. Select the Allow login prompt(ifall configured protocols fail)check box.
4. Click OK.
After you finish
Enter your user nameandpasswordto accessPI Data Archiveeach new Excelsession.Youcan
access the connection prompt by searching PI Data Archivewith the Search tool or by
connectingmanuallyfromConnectionManager.SeeEnterlogincredentialsfromConnection
Manager.
Enter login credentials from Connection Manager
Ifyou connect to PI Data Archiveby logging in asa PI user,thenyoumust enteryour username
and password foreach PI Data Archive you connectto during each Excel session.
Before you start
Configure a computerto allow explicitlogin prompts.
Procedure
1. On thePI DataLinktab,intheResourcesgroup,clickSettingsto opentheSettings window.
2. Click Connection Manager to open the Servers window.
3. In the list ofservers,right-click thePI Data Archive server thatyou wantto connectto,and
then click ConnectAs to open the Connect toPIData Archive window.
4. From the Authentication list, select PI User Authentication.
IfthewindowdoesnotshowtheAuthentication list,thenyoumustconfigurethecomputer
to allow explicit loginprompts.
5. Enter you username and password,and then click OK.
Eliminate timeout exception error
SearchesofPI Data Archiveservers with large point databasesmight reach thedata timeout
before PI Data Archive returnsall results.Youwill receivethe following error:
OSIsoft.PI.Net.PITimeoutException: [-10722] PINET: Timeout on PI RPC or
System Call.
To eliminate the error, use Connection Manager to increase the data timeout value.
Procedure
1. On thePI DataLinktab,intheResourcesgroup,clickSettingsto opentheSettings window.
2. Click Connection Manager to open the Servers window.

Troubleshooting
3. Right-clickthePIDataArchiveserverthatreturnedtheerror,andthenclickPropertiesto
open the PIData Archive Properties window.
4. Increasethevalueofthe Data Timeoutfield, and then click OK.
Data does not update
PIDataLinkcachesconfigurationdataforPI pointsandnon-time-baseddatafromPIAF(that
is, data other than PI point data references and events). As a result, data inserted into
worksheetsmaynotupdatetoshowvaluesbasedonchangedconfigurationornon-time-based
data,evenwhenyourecalculatethefunction.Beforecalculatingafunction,PI DataLinkchecks
when the cachewas last cleared; ifthecachehas not been cleared within thelast six hours,PI
DataLink automatically clearsthecache.To clearthecacheand obtainupdated datasooner,do
one ofthe following:
• Click Clear Cache on theSettings window.SeeManagePIDataLink settings from Excel.
• Close and reopen Microsoft Excel.

Technical support and other resources
Fortechnicalassistance,contactOSIsoftTechnicalSupportat+1510-297-5828orthroughthe
OSIsoftTechSupportContactUspage(https://techsupport.osisoft.com/Contact-Us/).The
website offersadditional contactoptions forcustomers outsideoftheUnitedStates.
When you contact OSIsoft Technical Support, be preparedto provide this information:
• Product name, version, and build numbers
• Details about yourcomputer platform(CPU type,operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details ofany environmentchangesprior to the start ofthe issue
• Summary oftheissue,includingany relevantlog files during thetimetheissueoccurred
To ask questions ofothers who useOSIsoft software,join theOSIsoft usercommunity,
PISquare(https://pisquare.osisoft.com).Membersofthecommunitycanrequestadviceand
share ideas about the PI System. The PI Developers Club space within PI Square offers
resourcesto helpyouwith theprogramming andintegration ofOSIsoft products.

Technical support and other resources

Pi data link-2017-sp1-user-guide-es-05

More Related Content

Similar to Pi data link-2017-sp1-user-guide-es-05

Recently uploaded

Pi data link-2017-sp1-user-guide-es-05