Differences

This shows you the differences between two versions of the page.

--- transformations:sharedmemory [2021/09/03 18:22] – [Key-value storage] dmitry
+++ transformations:sharedmemory [2021/10/17 16:37] – craigt
@@ Line 1: / Line 1: @@
+{{ transformations:SharedMemoryAction.png}}
  ====== SHARED MEMORY ======
 Category: Workflow / Internal
@@ Line 4: / Line 5: @@
 \\
 =====Description=====
-This action can perform the following operations with the shared memory (more on it below):
+This action can perform the following operations with the shared memory (details below):
   * Remember a value by a key
-  * Forget a value and the key associated with it
+  * Forget a value and its associated key
   * Recall a value by key
   * List keys and values
@@ Line 19: / Line 20: @@
 | CustomerDB\Last reload date  | 2021-09-03  |
-To obtain a value, one should know the key. Keys and values can be added and removed on demand with the help of the "Shared memory" action. The shared memory is stored in the centralized repository. Therefore any EasyMorph workflow can read (recall) and write (remember) keys and values in the shared memory at any moment as long as it has access to the repository.
+To obtain a value, one should know the key. Keys and values can be added and removed on demand with the help of the //Shared memory// action. The shared memory is stored in a centralized repository. Therefore any EasyMorph workflow can read (recall) and write (remember) keys and values in the shared memory at any moment as long as it has access to the repository.
+\\
 =====Use cases=====
 The shared memory can be convenient in many cases:
-  * Store temporary values - E.g. store the last loaded date when doing incremental loads.
+  * **Store temporary values:**  Store the last loaded date when doing incremental loads.
-  * Pass values between workflows and users - Similarly to the shared connectors, the shared memory can be accessed from different Desktops. Once a value is remembered, it can be accessed by all Desktops and Server spaces that use the same repository
+  * **Pass values between workflows and users:**  Similar to shared connectors, the shared memory can be accessed from different Desktops. Once a value is remembered, it can be accessed by all Desktops and Server spaces that use the same repository.
-  * Environment configuration - The shared memory can be used to store configuration settings that are different in PROD and TEST environments.
+  * **Environment configuration:**  The shared memory can be used to store configuration settings that are different in PROD and TEST environments.
-  * Workflow variable - While project parameters are constant and don’t change during a workflow run, the shared memory values can be set, removed, and changed in a single workflow
+  * **Workflow variable:**  While project parameters are constant and don’t change during a workflow run, the shared memory values can be set, removed, and changed in a single workflow.
-  * Lightweight data store - Sometimes, using a relational database to store and share just a few values looks like overkill. The shared memory can be more appropriate for such cases.
+  * **Lightweight data store:**  Sometimes, using a relational database to store and share just a few values seems like overkill. The shared memory can be more appropriate for such cases.
+\\
+=====Action settings=====
+^Setting^Description^
+|Command|Select the operation to perform on the shared memory repository.  Options:  //Remember//, //Recall//, //Forget//, and //List//.|
+\\
+====Remember settings====
+Description:  Store a value in an associated key.
+^Setting^Description^
+|Key<sup>*</sup>|Enter the key name associated with the value.  Nested keys are permitted using backlashes to define subkeys.\\  e.g.  mykeys\key1, mykeys\key2\subkey2a.|
+|Pick|This button opens a window used to navigate through the current key structure.|
+|Value<sup>*</sup>|Enter the value associated with the key provided above.|
+|If key already exists|Select how EasyMorph handles situations when the provided key already exists.  Options:  //Update value//, //Fail//\\ (display an error), or //Do nothing// (no action is taken).|
+<sup>*</sup> Setting can be specified using a [[:parameters|parameter]].\\
+\\
+====Recall settings====
+Description:  Retrieve the value stored in a specified key.
+^Setting^Description^
+|Key<sup>*</sup>|Enter the key name or key\subkey "path" to the value to be retrieved.|
+|Pick|This button opens a window used to navigate through the current key structure.|
+|Column name|Choose how the column in the action's output dataset will be named.  Options:  //Last subkey// (the name of the final key),\\ //Full key name// (the entire key/subkey path),  or //Custom//<sup>*</sup> (enter a column name).|
+|Append column|When //unchecked//, the output dataset will be a single cell containing the recalled value in a column named as selected\\ above.  When //checked//, a new column will be appended to the incoming dataset with the recalled value appearing in each row. |
+<sup>*</sup> Setting can be specified using a [[:parameters|parameter]].\\
+\\
+====Forget settings====
+Description:  Clear the value and associated key from the shared memory.
+^Setting^Description^
+|Key<sup>*</sup>|Enter the key name or key/subkey "path" to be removed.  This must be a lowest-level key or an error is displayed.|
+|Pick|This button opens a window used to navigate through the current key structure.|
+|If the key doesn't exist|Select how EasyMorph handles situations when the provided key does not exist.  Options:  //Fail// (display an error), or\\ //Ignore// (no action is taken).|
+<sup>*</sup> Setting can be specified using a [[:parameters|parameter]].\\
+\\
+====List settings====
+Description:  Generate a list of key-value pairs along a certain key/subkey path.
+^Setting^Description^
+|Keys start with<sup>*</sup>|Enter a whole or portion of a key name or key/subkey "path" from which a list of key-value pairs will be generated.\\  Entering the lowest-level key name will provide a single record with that key-value pair.  Entering a higher-level key name\\ will produce a multi-record dataset of all subkeys and values under the entered key.|
+|Pick|This button opens a window used to navigate through the current key structure.|
+<sup>*</sup> Setting can be specified using a [[:parameters|parameter]].\\
+**For example:**\\
+Keys start with "mykeys\key1" produces a dataset with a single key-value pair:
+^Key^Value^
+|mykeys\key1|  12|
+Keys start with "mykeys" produces a dataset listing all subkeys with their associated values:
+^Key^Value^
+|mykeys\key1|  12|
+|mykeys\key2|  79|
+|mykeys\key3|  247|
 \\
 =====Remarks=====
-It is recommended to use the backslash (\) to create nested keys.
+====Using shared memory====
+  * Use a backslash (\) to create nested keys.
+  * Values are remembered in the shared memory and recalled in native [[syntax:types|EasyMorph data types]]. Errors cannot be remembered (stored) by design.
+  * You can store large text objects, such as JSON, in the shared memory.
+  * All stored data is encrypted and cannot be accessed from outside of EasyMorph.
+====Accessing shared memory====
+  * The same access restrictions as for data [[:connectors|connectors]] apply.
+  * The shared memory supports simultaneous operations from different computers as long as they can access the same repository.
+  * Depending on repository location, network performance, and size of the stored keys and values, the shared memory can handle up to 100 operations per second.
+\\
+=====Examples=====
+Below is a sample process for manipulating the shared memory.
+**Store values:**\\
+> Command:  REMEMBER
+> Key:  mykeys\key1
+> Value:  100
-The same access restrictions as for data connectors apply.
+> Command:  REMEMBER
+> Key:  mykeys\key2
+> Value:  200
-The shared memory supports simultaneous operations from different computers as long as they can access the same repository.
+\\
+**List keys-values:**\\
+> Command:  LIST
+> Keys start with:  mykeys
+> Show last changed time is checked.
-Values are remembered in the shared memory and recalled in native [[syntax:types|EasyMorph data types]]. Errors can’t be remembered by design.
+^Key^Value^Last changed^Changed by^
+|mykeys\key1|100|17-Oct-2021|UserName  |
+|mykeys\key2|200|17-Oct-2021|UserName  |
-You can store large text objects, such as JSON in the shared memory.
+\\
+**Retrieve a value:**\\
+> Command:  RECALL
+> Key:  mykeys\key1
+> Column name:  Last subkey
-All stored data is encrypted and can't be accessed from outside of EasyMorph.
+^key1^
+|100|
-Depending on repository location, network performance, and size of the stored keys and values, the shared memory can handle up to 100 operations per second.
+\\
+**Clear a key-value pair:**\\
+> Command:  FORGET
+> Key:  mykeys\key1