Name-value pair support

Name-value pair support is a method to save data at one point in the life of an entry control block (ECB) and to retrieve this data later in the life of the ECB by using a predefined user specified name. One use of name-value pair support is for user credentials. When a transaction is authorized, you can save the credential as a data value with a predefined user specified name. Later in the life of the ECB if the credential is needed for further authorization, you can retrieve the credential by using the predefined name.

Name-value pair

A name-value pair consists of a data value and a name that is used to identify the data value. A data value exists in the ECB until a request is made to remove the data value or until the ECB exits.

The following actions are supported to manage name-value pairs:
  • You can set a name-value pair or change the data value of a name-value pair for an ECB by using the tpf_nameValueLocalSet function. You can set multiple name-value pairs for one ECB.
  • You can get the data value of a name-value pair for an ECB by using the tpf_nameValueLocalGet function.
  • You can remove one name-value pair or all name-value pairs for an ECB by using the tpf_nameValueLocalRemove function. For example, you can use this function in the following situations:
    • You want to remove one name-value pair or all name-value pairs that are copied from a parent ECB to a child ECB.
    • You want to ensure that the name-value pair area of a long-running ECB is clean before the ECB processes the next message.

Name-value pair area

The name-value pair area is a permanently allocated in-memory area in an ECB where name-value pairs are saved. The ECB-unique name-value pair area is allocated in restart by CCCTIN, the initializer program. When an ECB creates a child ECB, the name-value pairs in the parent ECB are copied to the child ECB. The contents of the name-value pair area are included in dumps.

You can set the size of a name-value pair area in the system initialization process (SIP) by using the CORREQ macro. The default and minimum size is 256 bytes, and the maximum size is 4096 bytes. You also can change the size of a name-value pair area by using the ZCTKA ALTER command. An error message is issued when there is not enough space in the name-value pair area for the name-value pairs.

Each name-value pair area has a 16-byte header and each name-value pair contains 12 bytes of control information. For example, if you allocate 256 bytes for the name-value pair area, the available space for name-value pairs is less than 256 bytes.

In a thread process, the name-value pair area is thread unique. Each ECB or thread has a name-value pair area. When the pthread_create function is called to create a new thread, the name-value pairs from the ECB that calls the pthread_create function are copied to the name-value pair area of the new thread.