List services assign entry key values to list entries when an entry is created (WRITE) or moved (MOVE). You can have list services assign the list entry key on a WRITE or MOVE request, you can explicitly specify an entry key on a WRITE or MOVE request, or you can leave an existing entry key value unchanged. See Creating a New List Entry and Figure 1.

For structures that are allocated in a coupling facility with CFLEVEL=1 or higher, you can have a list entry key assigned automatically. The value of the key is derived from a list control associated with the list — LISTKEY, the list key value, and is limited by another list control — MAXLISTKEY, the maximum list key value, an upper boundary for the value. You can set these two values with a WRITE_LCONTROLS request and read them with a READ_LCONTROLS request.

List services use the list key value and the maximum list key value when automatically assigning an entry key. You specify on your WRITE or MOVE request with the LISTKEYTYPE keyword whether you want the entry key to be set only if, as a result of the request, an entry is created, is moved, or is either created or moved. Optionally, you also can specify that an increment (LISTKEYINC) is to be applied to the list key value after the entry key has been automatically assigned. If adding the increment to the list key value would result in a value that exceeds the maximum list key value, the list operation is suppressed and you receive notification of the failure with reason code IXLRSNCODEMAXLISTKEY. When such a failure occurs, you should first determine whether you specified an incorrect list key increment. Depending on the protocol you are using for assigning list key values, you might want to issue a WRITE_LCONTROLS request to update either the list key value to a lower value or the maximum list key value to a higher value.