({{, (RefLink[PersistentValue, paclet:ref/PersistentValue])["name"] 
represents the persistent value associated with the key "name".}, {, (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",loc]
represents the persistent value associated with name stored in persistence location loc. }, {, (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",{(Subscript[loc, 1]),…}]
represents the persistent value associated with name at the first of the locations (Subscript[loc, i]) at which it occurs.}})

OpenersNotesSection(Spacer1)Details and Options

(RefLink[PersistentValue, paclet:ref/PersistentValue])["name",…] evaluates to give the corresponding persistent value.

(RefLink[PersistentValue, paclet:ref/PersistentValue])["name",…]=value or (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",…]:=value can be used to set persistent values.

(RefLink[PersistentValue, paclet:ref/PersistentValue]) allows the following options:

In (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",loc], possible forms for the persistence location loc include:

Supported location types include:

(RefLink[PersistentValue, paclet:ref/PersistentValue])["name"] is equivalent to (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",(RefLink[$PersistencePath, paclet:ref/$PersistencePath])].

(RefLink[PersistentValue, paclet:ref/PersistentValue])["name"]=value is equivalent to (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",(RefLink[$PersistenceBase, paclet:ref/$PersistenceBase])]=value.

(RefLink[PersistentValue, paclet:ref/PersistentValue])["name",loc] is essentially (RefLink[PersistentObject, paclet:ref/PersistentObject])["name",loc]["Value"].

When a single persistence location is specified, as in (RefLink[PersistentValue, paclet:ref/PersistentValue])["name",loc,…], the setting for (RefLink[MergingFunction, paclet:ref/MergingFunction]) is not used.

Otherwise, with the setting (RefLink[MergingFunction, paclet:ref/MergingFunction])->f, the final value returned is the result of applying the function f to the list of values found at all persistence locations.

Unless specified otherwise by "MergingFunction" metadata in the (RefLink[PersistentObject, paclet:ref/PersistentObject]), (RefLink[MergingFunction, paclet:ref/MergingFunction])->(RefLink[Automatic, paclet:ref/Automatic]) is equivalent to (RefLink[MergingFunction, paclet:ref/MergingFunction])->(RefLink[First, paclet:ref/First]).

Before a new value is assigned in (RefLink[PersistentValue, paclet:ref/PersistentValue])[sym]=value, any specified value preprocessing function is applied to value before the value is assigned.

If the preprocessing function returns (RefLink[$Failed, paclet:ref/$Failed]), the assignment is not performed.

If no explicit setting for (RefLink[ValuePreprocessingFunction, paclet:ref/ValuePreprocessingFunction]) is given, the setting to use is looked up on (RefLink[$PersistencePath, paclet:ref/$PersistencePath]).

An expired persistent value is treated as nonexistent, and the underlying persistent object may be removed.

Persistent values can be removed with (RefLink[Remove, paclet:ref/Remove]). (RefLink[Remove, paclet:ref/Remove])[PersistentValue["name"]] is equivalent to (RefLink[Remove, paclet:ref/Remove])[PersistentValue["name",(RefLink[$PersistenceBase, paclet:ref/$PersistenceBase])]].

OpenersPrimaryExamplesSection(Spacer1)Examples  (18)

OpenersExampleSection0(Spacer1)Basic Examples  (3)

Assign a persistent value:

PersistentValue["myval"]=42

Retrieve a previously saved value:

PersistentValue["myval"]

Remember a value with front end session scope:

PersistentValue["myPackage","FrontEndSession"]="ChatTools`";

Use the saved value, even in a newly restarted kernel within the same front end session:

Needs[PersistentValue["myPackage"]]

Store values for the same name at different persistence locations:

PersistentValue["x","FrontEndSession"]=1;
PersistentValue["x","Local"]=2;

Retrieve the first value found:

PersistentValue["x"]

Retrieve the list of all values on (RefLink[$PersistencePath, paclet:ref/$PersistencePath]):

PersistentValue["x",MergingFunction->Identity]

OpenersExampleSection2(Spacer1)Options  (8)

OpenersExampleSubsection0(Spacer1)MergingFunction  (3)

Create a complement of persistent values with key "lval" at various locations:

PersistentValue["lval","FrontEndSession"]={};
PersistentValue["lval","KernelSession"]={11,12};
PersistentValue["lval","Local"]={1,{2,12}};

List all existing values for the key "lval" on (RefLink[$PersistencePath, paclet:ref/$PersistencePath]):

PersistentValue["lval",MergingFunction->Identity]

By default, only the first value is returned:

PersistentValue["lval"]

Join and flatten all sublists:

PersistentValue["lval",MergingFunction->Flatten]

Join all sublists:

PersistentValue["lval",MergingFunction->Apply[Join]]

Create a complement of persistent associations with name "aval" at various locations:

PersistentValue["aval","FrontEndSession"]=<|"key1"->2,"key2"->{3,4}|>;
PersistentValue["aval","KernelSession"]=<|"key1"->3|>;
PersistentValue["aval","Local"]=<|"key2"->2,"key3"->{8,9}|>;

List all existing values on (RefLink[$PersistencePath, paclet:ref/$PersistencePath]):

PersistentValue["aval",MergingFunction->Identity]

Merge the values of identical keys in the associations:

PersistentValue["aval",MergingFunction->Merge[Flatten]]

Define a default value for "mylist" with a custom merging function:

PersistentValue["mylist","Installation",MergingFunction->Flatten]={};

Define additional values at different persistence locations:

PersistentValue["mylist","Local"]=3;
PersistentValue["mylist","FrontEndSession"]={1,2};

For looking up values, the custom merging function is now used:

PersistentValue["mylist"]

OpenersExampleSubsection1(Spacer1)PersistenceTime  (2)

Define a persistent value that expires in 5 seconds:

PersistentValue["b1",PersistenceTime->5]=1;

After 5 seconds, it is no longer used:

PersistentValue["b1"]
Pause[5];PersistentValue["b1"]

Define a persistent object that expires in 5 days:

PersistentValue["b2",PersistenceTime->Quantity[5,"Days"]]=55;

Verify the expiration date of the underlying persistent object:

PersistentObject["b2",$PersistenceBase]["ExpirationDate"]

OpenersExampleSubsection2(Spacer1)ExpirationDate  (2)

Define a persistent value that expires at the beginning of the year 2020:

PersistentValue["e1",ExpirationDate->DateObject[{2020}]]=1;

Verify the expiration date of the underlying persistent object:

PersistentObject["e1",$PersistenceBase]["ExpirationDate"]

Define a persistent value that expires at the beginning of next year:

PersistentValue["e2",ExpirationDate->NextDate["Year"]]=2;

Verify the expiration date of the underlying persistent object:

PersistentObject["e2",$PersistenceBase]["ExpirationDate"]

OpenersExampleSubsection3(Spacer1)ValuePreprocessingFunction  (1)

Define a value preprocessing function for a particular persistent value that accepts only integers:

validateInteger[x_]:=If[IntegerQ[x],x,$Failed]

PersistentValue["int","Local",ValuePreprocessingFunction->validateInteger]=0;

Assign an integer at any persistence location:

PersistentValue["int","KernelSession"]=42;

Assigning anything else generates an error and the assignment is not performed:

PersistentValue["int","KernelSession"]=0.5;

PersistentValue["int"]

OpenersExampleSection3(Spacer1)Applications  (1)

List all existing persistent objects for the key "lval":

PersistentObjects["lval"]

Delete them:

DeleteObject[%]

OpenersExampleSection4(Spacer1)Properties & Relations  (5)

Persistent values are stored in persistent objects:

PersistentValue["v","KernelSession"]=2;

PersistentObject["v","KernelSession"]["Value"]

The default location of a new persistent object is given by (RefLink[$PersistenceBase, paclet:ref/$PersistenceBase]):

PersistentValue["nv"]=3;

PersistentObject["nv",$PersistenceBase]["Value"]

Create a complement of persistent values with key "v" at various locations:

PersistentValue["v","FrontEndSession"]=1;
PersistentValue["v","KernelSession"]=2;
PersistentValue["v","Local"]=3;
PersistentValue["v","Cloud"]=4;

Persistent values are by default searched on all locations given in (RefLink[$PersistencePath, paclet:ref/$PersistencePath]):

$PersistencePath

The first value found is returned:

PersistentValue["v"]

With (RefLink[MergingFunction, paclet:ref/MergingFunction])->(RefLink[Identity, paclet:ref/Identity]), all values found are returned in a list:

PersistentValue["v",MergingFunction->Identity]

Specify an explicit list of locations to search for values:

PersistentValue["v",{"KernelSession","Cloud"},MergingFunction->Identity]

Expiration times specified with (RefLink[PersistenceTime, paclet:ref/PersistenceTime]) are converted to absolute expiration dates:

PersistentValue["x","KernelSession",PersistenceTime->5]=1;

PersistentObject["x","KernelSession"]["ExpirationDate"]

Persistent values can be removed with (RefLink[Remove, paclet:ref/Remove]):

PersistentValue["x"]=42;

Remove[PersistentValue["x"]]

PersistentValue["x"]

OpenersExampleSection5(Spacer1)Possible Issues  (1)

Create two persistent values for "name" in different locations:

PersistentValue["val","KernelSession"]=42;
PersistentValue["val"]=43;

(RefLink[Remove, paclet:ref/Remove]) by default removes only the value in the location given by (RefLink[$PersistenceBase, paclet:ref/$PersistenceBase]):

Remove[PersistentValue["val"]]

PersistentValue["val"]

Remove all values that might exist anywhere in the locations given by (RefLink[$PersistencePath, paclet:ref/$PersistencePath]):

Quiet[Remove[PersistentValue["val",$PersistencePath]]]

PersistentValue["val"]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[PersistentObject, paclet:ref/PersistentObject])  ▪  (RefLink[PersistenceLocation, paclet:ref/PersistenceLocation])  ▪  (RefLink[$PersistencePath, paclet:ref/$PersistencePath])  ▪  (RefLink[$PersistenceBase, paclet:ref/$PersistenceBase])  ▪  (RefLink[PersistentObjects, paclet:ref/PersistentObjects])  ▪  (RefLink[InitializationValue, paclet:ref/InitializationValue])  ▪  (RefLink[ExternalValue, paclet:ref/ExternalValue])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Setting Persistent Values, paclet:guide/SettingPersistentValues])}, {▪(RefLinkPlain[Persistent Storage, paclet:guide/PersistentStorage])}})}})