Using key value storage
A interprocess communication or the communication between different threads is possible about key value storage. This functionality is enclosed in several functions. One process/thread set a shared memory key value pair and another process/thread read this value per key. A key/value pair can be read using function tpco_shmget and can be written tpco_shmset. A process/thread can set a key value pair and another process/thread can retrieve that key value pair. We differentiate between different storage classes local and share.
Storage classes local and share
The storage parameter controls the scope of validity within one process (local) or one an instance (share). In this way you can interchange information between:
-
different threads of one process (local)
-
different processes of one instance (share)
The storage value local mean the key value information can share within the same prcoess, but possible different threads, share mean the key value can share between different processes of one instance (the same BGS or APPS), in the case of share is the key value information persistent, over the life time of the program out. Following use cases are possible for share:
-
Sharing information between processes of an instance (between job agents or test scripts, running instances of a pipe)
-
Sharing information between processes after a restart (persistence),
You can use local for sharing information within the same process, but possible different threads.
Parameter key
This is the key on which the value is stored.
Parameter key pattern
This is the key pattern, can contains * for the search function.
Parameter value
This is the value assigned to key.
Parameter value pattern
This is the value pattern, can contains * for the search function.
Parameter noerr
This parameter is optional. If it is not specified, a TCL exception will be thrown if the key does not exist. You can evaluate the exception with the catch command. If the noerr parameter is specified, no exception will be thrown if the key does not exist. In this case the return value is the string "unknown key".
Parameter dump file
This parameter describes a regular output file name.
Parameter tout This parameter describes the life time of key/value pair (0 is meaning infinite).
Example: using storage class local
Communication between different threads using the storage class local.
2 set thid [thread::create]
3 thread::send -async $thid "tpco_shmset local XYZ 4212 3600" result
Example: using storage class share
Communication between different processes within one instance using the storage class share. Please consider that the key UVW is stored persistent and has validy about life time over the proocess out.
Example: using noerr parameter
The following code shows the difference, if the optional noerr parameter is used or not
6 "tpco_shmget local ABC"
◆ tpco_chvprocflag()
This function changes the value of a key from the shared memory.
- Deprecated:
- Please use the new function tpco_shmset.
- Parameters
-
key | Key on which the value is stored. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
-value | Value assigned to the key. |
-timeout | (optional), timeout in seconds or 0 for infinite validity |
- Returns
- 0 on success, 1 if any failure occurs
◆ tpco_delprocflag()
This function delete a key/value pair from the shared memory.
- Deprecated:
- Please use the new function tpco_shmdelete.
- Parameters
-
key | Key to get the timeout value for. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
- Returns
- 0 on success, 1 if any failure occurs
◆ tpco_getprocflag()
This function gets the value of a key from the shared memory.
- Deprecated:
- Please use the new function tpco_shmget.
- Parameters
-
key | Key on which the value is stored. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
- Returns
- the value of key on success, "unknown key" on error.
◆ tpco_getprocflagA()
This function gets the value of a key from the shared memory.
- Deprecated:
- Please use the new function tpco_shmget.
- Parameters
-
key | Key on which the value is stored. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
- Returns
- A list with following content, element 0 == 0 on success, element 0 == 1 on error. The element 1 contains the value of key on success, "" on error.
◆ tpco_getprocflagtout()
This function gets the timeout value of a key/value pair in the shared memory.
- Deprecated:
- Please use the new function tpco_shmgettout.
- Parameters
-
key | Key on which the timeout value will be get. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
- Returns
- 0 on success, 1 if any failure occurs
◆ tpco_setprocflag()
This function sets the value of a key from the shared memory. Please consider, that the value can not be overwritten. For this purpose, please use the function tpco_chvprocflag.
- Deprecated:
- Please use the new function tpco_shmset.
- Parameters
-
key | Key on which the value is stored. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
-value | The value assigned to the key. |
-timeout | (optional), timeout in seconds or 0 for infinite validity |
- Returns
- 0 on success, 1 if any failure occurs
◆ tpco_setprocflagtout()
This function sets the timeout value of a key/value pair in the shared memory.
- Deprecated:
- Please use the new function tpco_shmsettout.
- Parameters
-
key | Key on which the timeout value will be changed. |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
-timeout | (optional), timeout in seconds or 0 for infinite validity |
- Returns
- 0 on success, 1 if any failure occurs
◆ tpco_shmdelete()
This function deletes a key and value from the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
noerr | (optional) disable a tcl exception. See also noerr |
5 "tpco_shmdelete local X.Y.Z"
◆ tpco_shmdump()
(DEBUG) This function dumps the value of the shared memory into a file.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
fname | name of the dumpfile. See also dumpfile |
type | 0 always null |
- Returns
- none
3 4294967295-SYS.INFO.PLATFORM == unix
4 4294967295-CONFIG.UDPSRV.ATTACH.SIZE == 268435456
5 4294967295-CONFIG.UDPSRV.ATTACH.PATH == /home/joerg/work/TR1570_5965/tp_core_Linux_x86_64_debug/var/log/attach.ca
6 4294967295-CONFIG.APPSRV.DEBUGGER.POLLRATE == 1200
7 4294967295-CONFIG.TEST.INPUT.TIMEOUT == 31536000
8 4294967295-CONFIG.TEST.LOG.PASSWORD == off
9 4294967295-SYS.INFO.NETDEBUGLOGNAME == sys/nihil/BGS_20121002-113726/tpinshell64_netd.log
10 4294967295-SYS.INFO.OS == Linux
◆ tpco_shmexists()
This function tests the existence of a key in the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
noerr | (optional) disable a tcl exception. See also noerr |
- Returns
- 1= exists 0= does not exist
◆ tpco_shmexset()
This function writes a key value in the shared memory (exclusively).
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
value | the key value. See also value |
tout | lifetime of the key (0=infinitely). See also tout |
noerr | (optional) disable a tcl exception. See also noerr |
2 if {[
catch {
tpco_shmexset local A.B.C EXTEST 0}]} {
puts $::errorInfo}
5 "tpco_shmexset local A.B.C EXTEST 0"
◆ tpco_shmget()
This function gets the value of a key from the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
noerr | (optional) disable a tcl exception. See also noerr |
- Returns
- the key value section value
◆ tpco_shmgettout()
This function gets the timeout of a key in the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
tout | lifetime of the key (0=infinitely). See also tout |
- Returns
- the timeout in seconds
◆ tpco_shmIntegrityCheck()
This function checks the integrity of the shared memory.
- Parameters
-
storage | storage to be tested; pass local (process memory) or share (instance memory). See also storage |
- Returns
- OK if the shared memory is intact, ERROR otherwise
◆ tpco_shmsearch()
This function searches keys and values in the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key-pattern | tcl string pattern to search in the keys (as well as string match). See also key_pattern |
value-pattern | tcl string pattern to search in the values (as well as string match). See also value_pattern |
- Returns
- the search result TCL-List {Key Value Timeout} {Key Value Timeout} ...
2 {SYS.INFO.OS Linux -1 }
◆ tpco_shmset()
This function writes/overwrites a key value in the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
value | the key value. See also value |
tout | lifetime of the key (0=infinitely) tout |
noerr | (optional) disable a tcl exception. See also noerr |
◆ tpco_shmsettout()
This function sets the timeout of a key in the shared memory.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
key | name of the memory key. See also key |
tout | lifetime of the key (0=infinitely). See also tout |
- Returns
- none
3 {X.Y.Z 123 1349320230 }
◆ tpco_shmstat()
(DEBUG) This function returns the shared memory statistics.
- Parameters
-
storage | local=process memory share=instance memory. See also storage |
- Returns
- statistics string
2 TOTAL=109 ACTIVE=108 MEMSZ=19896 OVERLOAD=1.019 - /105/2/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0/0
◆ tpco_tlsprocflag()
This function searches keys in the shared memory.
- Deprecated:
- Please use the new function tpco_shmsearch.
- Parameters
-
pattern | Pattern to search for in all keys, wildcards are allowed |
-persistent | (optional), 1 for persistent storage and sharing within processes of one instance, 0 otherwise |
- Returns
- 0 on success, 1 if any failure occurs