Creating a New List Entry

If your write request will cause (ENTRYTYPE=NEW) or might cause (ENTRYTYPE=ANY) a new list entry to be created, you can either provide the information necessary to create and position the new list entry or have the list service position the new list entry according to the defaults for the parameters you omit. In addition to specifying the list number (LISTNUM) of the list to receive the new entry, you need to provide the following information.

For a list structure with entry names: You must provide a list entry name (ENTRYNAME) for the list service to use if it creates a new list entry for you.

The list service uses the value of LISTPOS to determine whether to place the new list entry at the head or tail of the target list. If you specify LISTPOS=HEAD, the list service places the list entry at the head of the list. If you specify LISTPOS=TAIL, the list service places the list entry at the tail of the list.

For ENTRYTYPE=ANY:
- If you specify both the ENTRYID and ENTRYNAME parameters, the list service uses the value of ENTRYID to check for an existing list entry, and the value of ENTRYNAME to assign a name to a new entry.
- If a list entry already exists with the specified name, the list entry is updated.
For ENTRYTYPE=NEW: if a list entry already exists with the name you have specified for the new entry, the WRITE request fails.

For a list structure with entry keys: You can provide a list entry key (ENTRYKEY), have the list service assign a list entry key as shown in Table 1, or have the list service automatically assign a list entry key from the list control value. List entries in each list are maintained by key in ascending order. The list service places a new list entry on the target list as follows:

Table 1. Rules for Placement of Keyed List Entry for REQUEST=WRITE
ENTRYKEY Specified?	LISTPOS Value	Existing Entries With Same Key?	Position for New List Entry
Yes	HEAD or TAIL	No	Positioned to maintain ascending order of keys.
Yes	HEAD	Yes	Before the first list entry with the same key.
Yes	TAIL	Yes	After the last list entry with the same key.
No	HEAD	Not applicable	At head of list. List entry key initialized to binary zeros.
No	TAIL	Not applicable	At tail of list. List entry key initialized to binary ones.

When you specify automatic list entry key assignment with LISTKEYTYPE, the list service uses the key value that was automatically assigned to follow the same placement rules as if you had explicitly specified ENTRYKEY.

If you specify a locking operation (LOCKOPER) to be performed with a write operation, the list service performs the locking operation as described under Table 1.