Method and apparatus for processing a list structure6963882Abstract Various enhancements are made to the architecture of a list processor to facilitate its use in implementing a message queue that is shared by queue managers residing across a multisystem complex. A new list structure control—a program list entry identifier indicator, or PLEIDI—is defined to allow the user to specify whether user-defined entry IDs are used when the list is allocated. A new delete list (DL) command is added that sequentially processes list entries in the order in which they exist on the specified list. A new move list entries (MLES) command provides a performance-optimized means to process an input list of entries. New key comparison functions and list monitoring enhancements have also been added. A new type of key called a secondary list entry key (SLEK) allows the user to specify a secondary key value as a means to identify a list entry. Claims 1. In an information handling system in which operations are performed on a list structure by a list structure processor in response to requests received from a requester, a method of processing a list structure, comprising the steps of: Description BACKGROUND OF THE INVENTION
It would be desirable to be able to use the list-processing capabilities of the coupling facility to implement a message queue that is shared by queue managers residing on different systems across a sysplex. To be suitable for this purpose, the CF list architecture should allow MQSeries to efficiently implement the following message-queuing semantics:
SUMMARY OF THE INVENTION The present invention contemplates extensions to the CF list architecture that allow MQSeries to efficiently exploit the CF list model and provide for shared queues in a Parallel Sysplex emvironment. The present invention is not limited to use in a message queueing environment, however, but may be used in other applications as well. One aspect of the present invention contemplates a program-specified unique list entry identifier (ID) in place of the list entry ID generated by the system. In a parallel implementation of MQSeries, the CF list architecture should allow user-generated list entry identifiers to be used as a direct entry-locating mechanism in order to insure that the identifier for each list entry is unique across CF list structures and consistent between MQSeries queue managers. MQSeries could accomplish this in the existing architecture by using list entry names. However, entry names and entry keys are mutually exclusive means of specifying list entries, and MQSeries also requires the use of entry keys for identifying list entries. MQSeries requires a function that is equivalent to that provided today by entry IDs as a direct means of addressing a list entry in a list structure. Currently, however, entry IDs are generated internally by the coupling facility. In accordance with one aspect of the invention, a new list structure control—a program list entry identifier indicator, or PLEIDI—is defined to allow the user to specify whether user-defined entry IDs are used when the list is allocated. This new option is provided as an attribute of list structure allocation. Corresponding modifications may be made to the operating system components that exploit the CF list architecture. Thus, in the case of the OS/390 component known as Sysplex Services for Data Sharing (XES), an optional input may be added to the XES Connection Service that indicates whether the user wishes to provide unique list entry ID values or the system should generate entry ID values for each list entry created for the structure. A connect request is rejected if the connector's requested attribute does not match the attribute in effect for the current allocated instance of the structure. In a preferred embodiment, list entry ID type is consistent for a whole list structure. Either all list entries in the structure are referenced by entry IDs generated by the system, or all list entries are referenced by entry IDs provided by the user. Another aspect of the present invention contemplates a new delete list (DL) command. MQSeries requires an efficient means to delete entries from a given list without knowledge of the specific list entry IDs of the entries to be deleted. In accordance with this aspect of the invention, a new delete list command is added that sequentially processes list entries in the order in which they exist on the specified list. The starting point for the list entry selection is specified by the head or tail of the list, entry ID, entry name, entry key, secondary key or list cursor. The new delete list command allows specific criteria to be specified that provides a means to target only particular entries to be processed for deletion. This command scans entries on a particular list and does not involve a scan of the entire structure. The present invention also contemplates a new move list entries (MLES) command. A new command of this type is required by MQSeries to optimize the performance of two of their critical processes: committing MQPUT list entries and backing out of MQGET list entries. This requires updating each affected list entry, either by changing the list entry key while keeping the list entry on the same physical list in the CF list structure or by moving the list entry from one list back to its original list while the list entry key for the list entry remains unchanged. In accordance with this aspect of the invention, a new move list entries command has been added that provides a performance-optimized means to process an input list of entries. Each list entry in the input list may be moved to a new position on a list in the CF list structure by updating the list entry key, or each list entry may be moved from one list to another list in the coupling facility list structure by specifying a new target list number. The new move list entries command allows both the list number and the list entry key for a list entry to be updated. The new move list entries (MLES) command is a multiple-list entry command, which takes as input a list of specified entries to be processed. The move list entries command takes a list of entries identified by list entry ID or name. For each entry in the input list a target list number, a target list entry key and a target secondary key may be provided. In a preferred embodiment, a new input parameter—granular version number comparison (GVNC)—is provided on the move list entries (MLES) command to allow the user to optionally perform granular version number comparison. The move list entries command also allows granular version number replacement given the granular version number comparison was successful. A specified set of compare and replace criteria may be specified for each entry in the input entry list. In a preferred embodiment, the input operand granular version number comparison (GVNC) is also added to the delete list entries (DLES) command to allow the user to optionally perform granular version number comparisons with a specified compare value criterion specified for each entry in the input entry list. Currently, the DLES command supports nongranular comparison functions, that is, comparison is performed between a single specified compare value and each of the entries in the input entry list. By adding the granular version number comparison to both DLES and MLES, the commands are kept consistent. However, the DLES command is preferably not changed to support version number replacement because version number replacement on a delete request is not supported by the architecture; updating an entry that will be deleted does not make sense. In a preferred embodiment, another new operand—halt on miscompare (HOM)—is added to the move list entries (MLES) and delete list entries (DLES) commands to allow the user to specify whether execution should halt when a miscompare is encountered or continue to the next entry as is done currently. Miscompares may occur on the list entry version number, list entry key, list entry secondary key or list number. Currently, these commands skip an entry if a miscompare is encountered and continue processing with the next entry in the input list. This leads to the unfortunate circumstance that when any comparisons are requested, it is not possible for the user to determine which entries in the input entry list were deleted and which were skipped due to a miscompare because, upon completion the request only tells you how many entries were deleted. Another aspect of the present invention contemplates key comparison enhancements to the CF list architecture. MQSeries uses entry keys and entry version numbers to identify the list entries by MQSeries queue manager and priority. To accomplish this, key comparison enhancements have been added for both single- and multiple-entry commands. The key compare functions that have been added are as follows: Yet another aspect of the present invention contemplates the following list monitoring enhancements:
Yet another aspect of the present invention relates to keys. A new type of key, called a secondary key or, more particularly, a secondary list entry key (SLEK), is introduced that allows the user to specify a secondary key value as a means to identify a list entry. Secondary keys are associated with respective list entries and represent a second key ordering for each list in a CF list structure. A secondary key for an entry may be initialized, or set to null, when the entry is created. Secondary keys exist in parallel with primary keys and may be used and updated in a similar manner, as described below. In a preferred embodiment, a new list structure control called a secondary key indicator (SKI) is defined to allow for creation of secondary key control structures when the list is allocated. This allows the user to specify whether the keyed list structure should be allocated with only primary entry keys or with both primary and secondary entry keys. BRIEF DESCRIPTION OF THE DRAWINGS FIG. 1 shows a multiple-system complex (sysplex) incorporating the present invention. FIG. 2 shows a put list associated with a particular shared queue, with committed and uncommitted portions. FIG. 3 shows a get list associated with a particular shared queue manager. FIG. 4 shows the format of a list entry key falling within the uncommitted key range. FIG. 5 shows the format of a list entry key falling within the committed key range. FIG. 6 shows the movement of list entries between the uncommitted and committed portions of a put list. FIG. 7 shows the movement of list entries between a put list and a get list. FIG. 8A shows the procedure for writing a message to a queue. FIG. 8B shows the procedure for committing a write of a message to a queue. FIG. 8C shows the procedure for aborting a write of a message to a queue. FIG. 8D shows the procedure for reading (getting) a message from a queue. FIG. 8E shows the procedure for committing a read (get) of a message from a queue. FIG. 8F shows the procedure for aborting a read (get) of a message from a queue. FIG. 9 shows the coupling facility and the list structures that it contains. FIG. 10 shows a message command/response block. FIG. 11 shows a list structure. FIG. 12 shows a list. FIG. 13A shows a key range monitor table. FIG. 13B shows a list monitor table. FIG. 13C shows an event queue. DESCRIPTION OF THE PREFERRED EMBODIMENTS FIG. 1 shows the general configuration of a system complex (sysplex) 100 incorporating the present invention. Sysplex 100 comprises a plurality of systems 102 (an exemplary two of which, System A and System B, are shown), each of which is connected to a coupling facility (CF) 104 within which one or more shared message queues 106 are maintained. As is conventional, each system 102 comprises one or more processors and an operating system (not separately shown) and may constitute either a separate physical machine or a logical partition of a logically partitioned machine. Similarly, coupling facility 104 may constitute either a separate physical machine or a logical partition of a logically partitioned machine. Although the invention is not so limited, in a preferred embodiment the physical machines are IBM S/390 Parallel Enterprise Server® processors, while the operating system is the IBM OS/390® operating system. Within each system 102, user applications 110 perform sequences of operations, referred to herein as units of work (UOWs), on shared message queues 106 via a shared queue manager (SQM) 108 resident on that system. Shared queue managers 108 on different systems 102 that share the same message queue 106 are referred to herein as a queue-sharing group (QSG). In the preferred embodiment, each shared queue manager 108 in turn interacts with the coupling facility via a component 112 of the OS/390 operating system known as Sysplex Services for Data Sharing (XES). Sysplex Services for Data Sharing (XES) is described more fully in the IBM publication MVS/ESA Programming: Sysplex Services Guide, GC28-1495-02 (June 1995), incorporated herein by reference. User applications 110 on a system 102 interact with the shared queue manager 108 on that system via a series of Message Queue Interface (MQI) calls, the most important of which are MQPUT (to put a message onto a message queue 106) and MQGET (to get a message from a message queue 106). In response to such a call, shared queue manager 108 issues a call to XES 112 to invoke a requested system service (e.g., IXLLIST, IXLLSTC, IXLLSTE and IXLLSTM, as described below) to communicate with the coupling facility 104. In response to receiving a call from shared queue manager 108, XES 112 sends an appropriate message command block (MCB) containing data and other operands to the coupling facility 104 to perform the requested operation. XES 112 receives back from the coupling facility 104 a message response block (MRB) containing data and/or a response code. FIG. 10 shows the format of a message command/response block 1000 used for communications between the coupling facility 104 and a particular system 102. Message command/response block 1000 comprises a message command block (MCB) 1002, a message response block (MRB) 1004, and an optional data block 1006. Message command block 1002 contains a command block 1008 and request operands 1010. Similarly, message response block 1004 contains a response descriptor 1012 and response operands 1014. Command block 1008 contains a command code (CC) specifying the type of operation to be performed by coupling facility 104, while request operands 1010 constitute input parameters, as described below. As part of its list-processing capability, coupling facility 104 performs requested operations on lists composed of one or more entries. Referring now to FIGS. 2 and 3, in accordance with one aspect of the present invention, each logical message queue 106 is implemented as a set of lists: a put list 202, comprising a put list header (PLH) and optionally one or more list entries 204, and one or more get lists 206, each comprising a get list header (GLH) and optionally one or more list entries 204. (The terms "list" and "list header" are used interchangeably herein in view of their one-to-one correspondence.) Each put list 202 is associated with a particular shared queue 106 and is shared by the shared queue managers 108 in the queue-sharing group. Each get list 206, on the other hand, is associated with a particular shared queue manager 108 and may be used for multiple shared queues 106. Each list entry 204 corresponds to a message. (The terms "list entry" and "message" are used interchangeably herein.) Associated with each list entry 204, along with a message and other data, is a list entry key LEK that may be used to determine the order of the entry 204 in the list 202 or 206. Keys LEK form the basis for partitioning the put list 202 into a committed portion 208, in which the keys LEK fall within a committed key range, and an uncommitted portion 210, in which the keys LEK fall within an uncommitted key range that does not overlap the committed key range. Lists 202 and 206 and key ranges 208 and 210 supply the mechanism for writing, reading and committing messages 204 in accordance with the present invention. More particularly, the process of 'hiding' uncommitted messages 204, hiding messages 204 that have been read and making committed puts globally visible is done simply by movement between list headers 202 and 206 and/or key assignment changes without the use of any explicit locking protocols. The keys LEK that a list entry (message) 204 can be assigned are defined by the shared queue manager 108, as described below. Referring to FIGS. 4 and 8A, when a message 204 is initially put (step 802), it is first assigned the following 16-byte key LEK in the uncommitted key range (step 804):
The set of list entries 204 whose key LEK begins with X'F6' define the uncommitted portion 210 of the (put) list header 202. Referring to FIGS. 6 and 8B, when an uncommitted message 204 (first byte of key LEK is X'F6') is committed (step 806), it is moved from the uncommitted portion 210 of the list header 202 to the committed portion 208 of the same list header 202. In this case, the list entry 204 moves from one position on the list header 202 to another position on the same list header 202. The movement is accomplished by changing the list entry's key LEK so that it falls within the committed key range (step 808). Referring to FIG. 5, the uncommitted put key LEK is changed to the following:
The set of list entries 204 whose keys begin with (00, 09) inclusive defines the committed portion 208 of the put list header 202. Referring to FIG. 8C, if a unit of work decides to abort a write of a message 204 (step 810), it deletes the message 204 from the uncommitted portion 210 of the put list 202 (step 812). This portion 210 of the put list is available only to the unit of work that originally wrote the message 204 and is invisible to other units of work. Referring to FIGS. 7 and 8D, when a unit of work requests the highest committed message 204 on a get request (step 814), only the committed portion 208 of the list header 202 is eligible to be scanned, that is, list entries 202 whose keys begin with (00, 09) inclusive. Entries 204 that begin with X'F6' do not participate in the scan. This is accomplished by using an IXLLSTE invocation (as described below) that examines the entry 204 at the head of the list 202 (step 816) and returns it only if the first byte of its key is in the inclusive range (00, 09). (This is referred to herein as key range checking on read.) If there are no messages 204 on the list header 202 or if the key of the message at the head of the list header begins with a value greater than or equal to X'F6' (step 818), then no message is returned (step 820). If there are committed messages 204, then the message 204 that is returned is the message at the head of the list header 202, since the messages 202 are in priority order and within priority by time of arrival. Thus, if the message 204 at the head of the list 202 is a committed message (step 818), then two things happen in an atomic fashion: Once the message 204 is moved to the shared queue manager 108's uncommitted get queue 206, it is no longer visible to other get requests because all get requests for the shared queue 106 reference the shared queue's put list header 202. The final disposition of the message read will be either commit or abort. Referring to FIG. 8E, if the disposition is commit (step 826), the message 204 is deleted from the shared queue manager 108's uncommitted get queue 206 (step 828). Referring to FIG. 8F, if the disposition is abort (step 830), then the message 204 is moved back to the committed put list header 202 from whence it came into its proper priority/time sequence position (step 832). The list architecture of coupling facility 104, insofar as it is pertinent to the present application, will now be described. Referring to FIG. 9, coupling facility 104 contains microcode 904, also referred to as coupling facility control code (CFCC), for managing one or more list structures 902. Referring to FIG. 11, each list structure 902 contains a set of list structure controls 1102, a list set 1104 comprising one or more lists 1106, user controls 1108, a lock table 1110 comprising one or more lock table entries (LTEs) 1112, and one or more event queue controls 1114 and corresponding event queues 1116. Referring to FIG. 12, each list 1106 contains list controls 1202 (including a a key range monitor 110 table 1204 and a list monitor table 1206) and, optionally, one or more list entries 1208. Each list entry 1208 in turn contains a set of list entry controls 1210 (including a list entry ID LEID and a list entry key LEK), a data list entry 1212 comprising one or more list elements (LEs) 1214, and an adjunct list entry 1216 (including a secondary list entry key SLEK if defined). List Structure Controls 1102 The fixed list structure controls 1102 are initialized when the list structure 902 is created and remain unchanged until it is deallocated. The program-modifiable list structure controls 1102 are initialized when the list structure 902 is created. The program-modifiable control values may be changed by commands or CF processes. The fixed list structure controls 1102 are summarized in the following table.
The program-modifiable list structure controls 1102 are summarized in the following table.
Entry Reapportionment-in-Progress Indicator (EREIPI): Indicates whether an entry-to-element reapportionment process is currently active for the list structure 902. Event Monitor Controls Count (EMCC): Specifies the number of event monitor controls objects 1306 currently in a list set 1104. Extended User Structure Control (EUSC): An extension to the user structure control. List Count (LC): Specifies the number of lists 1106 created. List Element Characteristic (LELX): Specifies the number of bytes in each list element 1214. List Set Cursor (LSCUR): An integer that is either zero or contains the value of the current list number in the list set scan process. List Set Element Count (LSELC): Specifies the number of list elements 1214 that have been assigned to list entries 1208 or retry-data blocks, or both, in the list set 1104. List Set Entry Count (LSEC): Specifies the number of existing list entries 1208 in the list set 1104. List Structure Type (LST): Indicates the list objects 1106 created on allocation. The first flag is a secondary key indicator (SKI), the second flag is a program list entry identifier indicator (PLEIDI), the third flag is a element count indicator (ECI), The fourth flag is a lock indicator (LI), the fifth flag is a data indicator (DI), the sixth flag is an adjunct indicator (AI), the seventh flag is a name indicator (NI), and the eighth flag is a key indicator (KI). The secondary key indicator indicates whether secondary keys are supported. The program list entry identifier indicator indicates whether the structure uses a coupling facility-assigned LEID value or a program-assigned LEID value. The element count indicator indicates whether (1) list entry count and list entry count limit are defined or, alternatively, (2) list element count and list element count limit are defined. The lock indicator indicates whether a lock table is created. The data and adjunct indicators indicate respectively whether list entries have data entries and adjunct entries. The name indicator indicates whether list entries are named. The key indicator indicates whether list entries are keyed. At least one of the lock, data or adjunct indicators is active (i.e., indicates that the condition is true). The name indicator and the key indicator are never both active. For the dequeue event monitor controls (DEMC), read event monitor controls (REMC), read event queue controls (REQC), and register event monitors (REMS) commands, the key indicator must be active; otherwise, the list structure type is invalid and a request exception is recognized. Marginal Structure Size (MRSS): Specifies the minimum number of 4K-byte units of CF storage that are required for the creation of the requested lock table entries 1112, lists 1106, and associated controls for the list structure 902, independent of either the storage increment size or the requested target entry-to-element ratio. Maximum Data List Entry Size (MDLES): Specifies the maximum size of the data list entry 1212 as an integral multiple of the list element size. Maximum Event Monitor Controls Count (MEMCC): Specifies the maximum number of possible event monitor controls objects 1306 in a list set 1104. Maximum List Set Element Count (MLSELC): Specifies the maximum number of list elements 1214 that are available for assignment to list entries 1208 or retry-data blocks, or both, in the list set 1104. Maximum List Set Entry Count (MLSEC): Specifies the maximum number of possible list entries 1208 in a list set 1104. Maximum Structure Size (MXSS): Specifies the maximum number of 4K-byte units of CF storage that can be allocated for the list 1106. Minimum Apportionable Structure Size (MASS): Specifies the minimum number of 4K-byte units of CF storage that can be allocated for the list 1106, in integral multiples of the CF storage increment, that are sufficient for creating the requested lock table entries 1112, lists 1106, associated controls, enough event monitor controls 1306 and list entries 1208 with their associated controls to substantially satisfy the target monitor-to-entry storage ratio, and enough entries and elements to substantially satisfy the target entry-to-element ratio. Monitor Reapportionment-in-Progress Indicator (MREIPI): Indicates whether a monitor-to-entry storage reapportionment process is currently active for the list structure 902. Pending Entry-to-Element Ratio (PETELR): Contains the last requested target entry-to-element ratio on an allocate list structure command. The PETELR object is updated when the list structure 902 is initially allocated and when a reapportionment process is initiated. Pending Monitor-to-Entry Storage Ratio (PMTESR): Contains the last requested target monitor-to-entry storage ratio on an allocate list structure command. The PMTESR object is updated when the list structure 902 has been initially allocated and a monitor-to-entry storage reapportionment process is requested. Reapportionment-in-Progress Indicator (REIPI): Indicates whether a reapportionment process is currently active for the list structure 902. Structure Authority (SAU): A value associated with each bit in the SID vector. Structure Size (SS): Specifies the number of 4K-byte units allocated. Structure Size Change Indicator (SSCI): Indicates whether an expansion or contraction process is currently active for the list structure 902. Target Maximum Element Count (TMELC): Specifies the target for the maximum number of list elements 1214 that are available for assignment to list entries 1208 or retry-data blocks, or both, in the list set 1104. Target Maximum Entry Count (TMEC): Specifies the target for the maximum number of possible list entries 1208 in a list set 1104. Target Maximum Event Monitor Count (TMEMC): Specifies the target for the maximum number of event monitor controls objects 1306 that are available for registration of interest in subsidiary lists within the list set 1104. Target Structure Size (TSS): Specifies the target number of 4K-byte units to be allocated. User Identifier Vector (UIDV): A bit string with an initial value of zero. The bit positions start at zero and increase sequentially to the user identifier limit. The bit at position (i) in the string is set to one when a user is assigned with a UID value of (i). The bit at position (i) is reset to zero when a user is unassigned. User Structure Control (USC): A field per structure defined by the user. User Controls 1108 The user controls 1108 are created and initialized when a list structure user (such as a CF Manager component of shared queue manager 108, as described below) is assigned and are deleted when the list structure user is unassigned.
List Notification Token (LNT): Specifies a list notification vector to the system. System Identifier (SYID): A value specified by the program when a message path is activated. The system identifier is maintained in the message path status vector and copied into the user controls 1108 when an attach list structure user command is communicated over the message path. User Attachment Control (UAC): A field per attached user defined by the user. User Authority (UAU): A value that is compared and conditionally updated. User State (US): Specifies whether the user is attached. Lock Table 1110 The lock table 1110 is a sequence of objects 1112, called lock table entries. The number of lock table entries 1112 is determined when the table is created. The lock table entries 1112 are numbered from zero to the lock table entry count less one. Each lock table entry 1112 has a global lock manager (GLM) object and an optional local lock managers (LLM) object. A lock table entry 1112 whose size is one byte has only a global lock manager object. When a lock table entry size is greater than one byte, the leftmost byte is the global lock manager object, and the remaining bytes form the local lock managers object. Lock tables 1110 with an entry size of one byte do not support local lock managers. Lock tables 1110 with an entry size of at least two bytes do support local lock managers. The global lock manager object of a lock table entry 1112 contains an unsigned binary number called a user identifier. The local lock managers object of a lock table entry 1112 contains a string of local lock bits, where each bit represents a user identifier. The bits in the object are numbered from left to right, starting at the value zero and proceeding upward to the bit for the highest valid user identifier. The lock table objects have a value of zero when the table is allocated and may be modified by subsequent commands. Event Queue Controls 1114 There is an event queue controls object 1114 for each event queue 1116 in a list structure 902. All of the event queue controls of an event queue 1116 with the exception of the key type, are initialized to zero when the event queue 1116 is created or when the associated list structure user is detached. The key type is initialized to primary for the primary event queue controls and is initialized to secondary for the secondary event queue controls. The event queue controls are summarized in the following table.
Event Monitor Controls Queued Count (EMCQC): Specifies the number of event monitor controls 1306 currently queued to the event queue 1116. Event Notification Entry Number (ENEN): Specifies a list notification vector entry associated with an event queue 1116. Event Notification Request Type (ENRT): Indicates whether the list notification vector summaries are to be updated when an empty to not-empty state transition occurs on an event queue 1116. When active, this flag causes a user to be notified of empty-to-not empty transitions. Event Queue Monitoring Active Bit (EQMAB): Specifies whether the user associated with the event queue 1116 is monitoring the event queue 1116. Event Queue Transition Count (EQTC): Specifies the number of empty to not-empty event queue transitions that have occurred. Key Type (KT): Indicates the key type (primary or secondary) of the event monitor controls 1306 that are queued on the event queue 1116. If the key type is primary, EMCs are queued for primary subsidiary lists; if the key type is secondary, EMCs are queued for secondary subsidiary lists. Event Queue 1116 An event queue 1116 is a sequence of objects called event monitor controls 1306 (FIG. 13C). There are zero, one, or two event queues 1116 created for each list structure user when the list structure 902 is allocated, depending on the list structure type. When the list structure 902 does not have keys, no event queues 1116 are created. When the list structure 902 has keys but not secondary keys, a single event queue 1116 is created for each user. This is referred to either as the event queue 1116 or the primary event queue 1116 When the list structure 902 has both keys and secondary keys, two event queues 1116 are created, a primary event queue 1116 that contains EMCs with list entry keys, and a secondary event queue 1116 that contains EMCs with secondary list entry keys. The event queues 1116 are deleted when the list structure 902 is deallocated. An event monitor controls object 1306 is always queued to the rightmost position and dequeued from the leftmost position of the queue. An event monitor controls object 1306 may be queued when (1) an empty to not-empty state transition occurs for a monitored subsidiary list, (2) notification of the initial subsidiary list state is requested on registration, or (3) a not-empty to not-empty state transition occurs for a monitored subsidiary list. An event monitor controls object 1306 may be withdrawn when a not-empty to empty state transition occurs for a monitored subsidiary list or when notification of the initial subsidiary list state is requested on registration, may be dequeued by means of the dequeue event monitor controls command, and may be deleted when a user deregisters interest in the subsidiary list or detaches from the list structure 902. List 1106 A list 1106 is a sequence of objects 1208, called list entries. The number of possible entries 1208, from one to 232, is determined when the list structure 902 is created. The relative position of a list entry 1208 in the sequence is determined when the entry is created and may be changed when any list entry 1208 is created, deleted, or moved. A list entry 1208 is located by means of a list entry identifier, list entry name, or by position. List positions may be ordered by the time sequence of when list entries 1208 are created on or moved to a list 1106 or list positions may be in key order. There may be one or two key orderings for a list 1106. If there is only one key ordering then list positions are ordered by increasing values of the list entry key. If two key orderings exist, then the primary key ordering is by increasing values of the list entry key and the secondary key ordering is by increasing values of the secondary list entry key. The size of the largest list 1106 is limited by the free space and the size of all the controls required to support the list structure 902. A list entry 1208 has up to two objects: a data list entry 1212 and an adjunct list entry 1216, depending on the list structure type. A data list entry consists of from one to MDLES list elements 1214. The data list entry size is determined when the data list entry is written. The list element size is a power of 2 that is at least 256 bytes. The adjunct list entry size is 64 bytes. A list entry 1208 exists when it is created and ceases to exist when it is deleted. Subsidiary List A subsidiary list is a list within a list 1106 where all list entries 1208 have the same key. There are two types, depending on the type of key. Primary subsidiary lists consist of list entries 1208 on the same list 1106 with the same list entry key. Secondary subsidiary lists consist of all list entries 1208 on the same list 1106 with the same secondary list entry key. A primary subsidiary list may only exist when a list set 1104 is created and the list entries 1208 are keyed. A secondary subsidiary list may only exist when a list set 1104 is created and secondary keys are supported in the structure. Adjunct Data Entry The adjunct data entry is a 64-byte storage object containing unformatted data. When the structure contains adjuncts and the adjunct format control bits in the list entry controls are inactive, the adjunct list entry is an adjunct data entry. Adjunct Secondary Key Entry: The adjunct secondary key entry is a storage object containing the secondary list entry key and a secondary adjunct data area. When the structure contains secondary keys and the adjunct secondary key entry indicator in the adjunct format control is active, the adjunct list entry is an adjunct secondary key entry. The adjunct secondary key entry objects are summarized in the following table.
Secondary List Entry Key (SLEK): Partially designates the position of the list entry 1208 in the list 1106 in secondary key order. Secondary Adjunct Data Entry (SADE): A storage object containing unformatted data. List Controls 1202 There is a list controls object 1202 for every list 1106 created in a list structure 902. All the list controls 1202 except the list entry count limit and the list element count limit are initialized to zero when the list structure 902 is created. The list controls 1202 are summarized in the following table.
Assignment Key (AK): Specifies the value assigned to a list entry key when a key assignment operation is executed for a list entry 1208 that is moved or created on the list 1106. Assignment Key Threshold (AKT): Specifies the maximum value of an assignment key. Cursor Direction (CDIR): Indicates how the list cursor is updated (left to right or right to left) when the list cursor is maintained or initialized by a write list controls command. Key Range Empty Notification Threshold (KRENT): Specifies a number which is one less than the number of list entries 1208 that must remain in the key range to suppress a not-empty-to-empty list notification. Key Range List Entry Key (KRLEK): Specifies the lower value of the key range. Key Range Maximum List Entry Key (KRMLEK): Specifies the upper value of the key range. Key Range Not-empty Notification Threshold (KRNENT): Specifies one less than the number of list entries 1208 required in the key range in order to generate an empty-to-not-empty list notification. List Authority (LAU): A value that is compared and conditionally updated. List Cursor (LCUR): A list entry identifier that identifies a list cursor position. List Element Count (LELC): Specifies the number of list elements 1214 currently in the list 1106. List Element Count Limit (LELCL): Specifies the maximum number of possible list elements 1214 in a list 1106. List Empty Notification Threshold (LENT): Specifies a number which is one less than the number of list entries 1208 that must remain in the list 1106 to suppress a not-empty-to-empty list notification. List Not-empty Notification Threshold (LNENT): Specifies one less than the number of list entries 1208 required on the list 1106 in order to generate an empty-to-not-empty list notification. List Entry Count (LEC): Specifies the number of list entries 1208 currently in the list 1106. List Entry Count Limit (LECL): Specifies the maximum number of possible list entries 1208 in a list 1106. Key Range Monitor Table 1204 The key range monitor table 1204 contains information used to process the list notification vector of each user who has registered interest in key range state transitions. The key range monitor table 1204 is a sequence of objects 1302 (FIG. 13A), called key range monitor table entries. The number of key range monitor table entries 1302 is determined when the table is created and is equal to the maximum number of list structure users plus one. The key range monitor table entries 1302 are numbered from zero to the user identifier limit. Each key range monitor table entry 1302 has a key range monitoring active bit object, a key range notification request type object and key range notification entry number object. Key Range Monitoring Active Bit (KRMAB): Specifies whether the user associated with the key range monitor table entry 1302 is monitoring the key range. Key Range Notification Entry Number (KRNEN): Specifies a list notification vector entry associated with a monitored key range. Key Range Notification Request Type (KRNRT): Indicates whether the list notification vector summaries are to be updated when an empty to not-empty state transition occurs on a monitored key range. When active, this flag causes the user to be notified of empty-to-not empty transitions. Key range monitor table entry 1302
List Monitor Table 1206 The list monitor table 1206 contains information used to process the list notification vector of each user who has registered interest in the state transitions of the list 1106. The list monitor table 1206 is a sequence of objects 1304 (FIG. 13B), called list monitor table entries. The number of list monitor table entries 1304 is determined when the table is created and is equal to the maximum number of list structure users plus one. The list monitor table entries 1304 are numbered from zero to the user identifier limit. Each list monitor table entry 1304 has a list monitoring active bit object, a list notification request type object and a list notification entry number object. List Monitoring Active Bit (LMAB): Specifies whether the user associated with the list monitor table entry 1304 is monitoring the list. List Notification Entry Number (LNEN): Specifies a list notification vector entry associated with a monitored list 1106. List Notification Request Type (LNRT): Indicates whether the list notification vector summaries are to be updated when an empty to not-empty state transition occurs on a monitored list 1106. List Monitor Table Entry
List Entry Controls 1210 There is a list entry controls object 1210 for every list entry 1208 within a structure. The list entry controls 1210 are initialized when a list entry 1208 is created and are deleted when a list entry 1208 is deleted. The list entry controls 1210 are summarized in the following table.
Adjunct Format Control (AFC): A bit string consisting of adjunct format bits. Each bit is associated with a particular adjunct format. The adjunct format control bits include an adjunct secondary key entry indicator and (2) an adjunct lock entry indicator. The bits are mutually exclusive; at most one bit is active. When all the bits are inactive, the adjunct list entry 1216 is unformatted and contains the adjunct data entry. Data List Entry Size (DLES): Specifies the size of the data list entry 1212 as an integral multiple of the list element size. List Entry Identifier (LEID): Designates the list entry 1208. List Entry Key (LEK): Partially designates the position of the list entry 1208 in the list 1106. List Number (LN): Designates the list 1106 that the list entry 1208 is in. Event Monitor Controls 1306 There is an event monitor controls object 1306 for every user and subsidiary list combination for which a user has currently registered interest. The number of possible event monitor controls 1306, from one to 232-1, is determined when the list structure 902 is created and may be changed when structure storage is expanded or contracted or the monitor-to-entry storage ratio is reapportioned. An event monitor controls object 1306 is created when a user initially registers interest and is deleted when a user deregisters interest in a subsidiary list or detaches from the list structure 902. All the event monitor controls 1306 except the event monitor queued indicator are initialized to the values provided as request operands 1010 during registration. The event monitor controls 1306 are summarized in the following table.
Aggressive Not-empty Notification Indicator (ANENI): When inactive, indicates that the event monitor controls 1306 should be queued to the event queue 1116 for only the first list entry 1208 added to a subsidiary list. When active, indicates that the event monitor controls 1306 should be queued to the event queue for every list entry 1208 that is added. Event Monitor Queued Indicator (EMQI): Indicates whether the event monitor controls object 1306 is queued to the event queue 1116 associated with the user ID contained within the object. List Entry Key (LEK): Partially designates the primary subsidiary list. List Number (LN): Partially designates the subsidiary list. Key Type (KT): Indicates the key type (primary or secondary) in the event monitor controls 1306. When the key type is primary, the key is a (primary) list entry key and the event monitor controls 1306 are associated with a primary subsidiary list. When the key type is secondary, the key is a secondary list entry key and the event monitor controls 1306 are associated with a secondary subsidiary list. Secondary List Entry Key (SLEK): Partially designates the secondary subsidiary list. User Identifier (UID): Identifies the user. User Notification Control (UNC): A field per event monitor controls 1306 defined by the user. List Structure Object States List States A list 1106 is either in the empty or the not-empty state. Empty State: A list 1106 is in the empty state when the number of list entries 1208 on the list 1106 is less than or equal to the list empty notification threshold. Not-empty State: A list 1106 is in the not-empty state when the number of entries on the list 1106 is greater than the list not-empty notification threshold. When the empty and not-empty notification thresholds for the list 1106 are not equal and the number of entries on the list 1106 falls between the list empty notification threshold and the list not-empty notification threshold, inclusive of the latter, the state of the list 1106 is determined as follows: List State Transitions A user may register interest in the state transitions of a list 1106 by means of the register list monitor command. A list 1106 may change either from the not-empty to the empty state or from the empty to the not-empty state. Empty to Not-empty List State Transition: A list 1106 that is in the empty state changes from the empty to the not-empty state when an entry is created on or moved to the list 1106 and the number of list entries 1208 on the list 1106 becomes one greater than the list not-empty notification threshold. Not-empty to Empty List State Transition: A list 1106 that is in the not empty state changes from the not-empty to the empty state when an entry is deleted from the list 1106 or moved to another list 1106 and the number of list entries 1208 on the list 1106 becomes equal to the list empty notification threshold. Key Range States A key range is either in the empty or the not-empty state. A user may request a notification of the initial state of a key range by means of the initial notification request type on the register list monitor command. Empty State: A key range is in the empty state when the number of list entries 1208 in the key range is less than or equal to the key range empty notification threshold. Not-empty State: A key range is in the not-empty state when the number of entries in the key range is greater than the key range not-empty notification threshold. When the empty and not-empty notification thresholds for the key range are not equal and the number of entries in the key range falls between the key range empty notification threshold and the key range not-empty notification threshold, inclusive of the latter, the state of the key range is determined as follows: Key Range State Transitions A user may register interest in the state transitions of a key range by means of the register list monitor command. A key range may change either from the not-empty to the empty state or from the empty to the not-empty state. Empty to Not-empty Key Range State Transition: A key range that is in the empty state changes from the empty to the not-empty state when (1) an entry is created in the key range, (2) an entry is moved to the key range, or (3) key range initialization completes, and the number of list entries 1208 in the key range becomes greater than the key range not-empty notification threshold when the number had previously been less than or equal to the threshold. Not-empty to Empty Key Range State Transition: A key range that is in the not empty state changes from the not-empty to the empty state when an entry is (1) deleted from the key range, (2) moved to another list 1106, (3) moved to the same list 1106 with a new list entry key that is outside of the key range, or (4) key range initialization completes, and the number of list entries 1208 in the key range becomes less than or equal to the key range empty notification threshold when the number had previously been greater than the threshold. Subsidiary List States A subsidiary list is either in the empty or the not-empty state. A user may request to queue or withdraw the event monitor controls object 1306 to reflect the initial state of a subsidiary list by means of the initial notification request type on the register list monitor or register event monitors command. Empty State: A subsidiary list is in the empty state when there are no entries in the subsidiary list. Not-empty State: A subsidiary list is in the not-empty state when there are one or more entries in the subsidiary list. Subsidiary List State Transitions A user may register interest in the state transitions of a subsidiary list by means of the register list monitor or register event monitors command. A subsidiary list may change either from the not-empty to the empty state, from the empty to the not empty state, or from the not-empty to the not-empty state. Empty to Not-empty Subsidiary List State Transition: A subsidiary list changes from the empty to the not-empty state when the subsidiary list has no entries and an entry is created or moved to the subsidiary list. Not-empty to Empty Subsidiary List State Transition: A subsidiary list changes from the not-empty to the empty state when the subsidiary list has one entry and the entry is deleted or moved to another subsidiary list. Not-empty to Not-empty Subsidiary List State Transition: A subsidiary list changes from the not-empty to the not-empty state when (1) the subsidiary list is not empty, (2) an entry is created or moved to the subsidiary list, (3) the event monitor queued indicator is active and the aggressive not-empty notification indicator is active in the associated EMC. Event Queue States An event queue 1116 is either in the empty or the not-empty state. A user may request a notification of the initial state of an event queue 1116 by means of the initial notification request type on the register list monitor command. Empty State: An event queue 1116 is in the empty state when there is no event monitor controls object 1306 queued to the event queue 1116. Not-empty State: An event queue 1116 is in the not-empty state when there are one or more event monitor controls objects 1306 queued to the event queue 1116. Event Queue State Transitions A user may register interest in the state transitions of an event queue 1116 by means of the register list monitor command. An event queue 1116 may change either from the not-empty to the empty state or from the empty to the not-empty state. Empty to Not-empty Event Queue State Transition: An event queue 1116 changes from the empty to the not-empty state when the event queue 1116 has no queued object and an event monitor controls object 1306 is queued to the event queue 1116. Not-empty to Empty Event Queue State Transition: An event queue 1116 changes from the not-empty to the empty state when the event queue 1116 has one event monitor controls object 1306 queued and the object is dequeued, withdrawn, or deleted. Creating a List Structure When a list structure 902 is created, the list structure type determines the attributes of the created structure. The list structure type has indicators for each of the following: program list entry identifier indicator, counters, locks, data, adjunct, name, key, and secondary key. When the program list entry identifier indicator in the list structure type specified is inactive and allocation is successful, the list structure 902 uses list entry identifier values that are generated by the coupling facility. When the program list entry identifier indicator in the list structure type specified is active and allocation is successful, the list structure 902 uses list entry identifier values that ate program assigned. When the element count indicator in the list structure type specified is inactive and allocation is successful, the list controls 1202 for each list 1106 contain a list entry count and a list entry count limit. When the count indicator in the list structure type specified is active and allocation is successful, the list controls 1202 for each list 1106 contain a list element count and a list element count limit. When the lock indicator in the list structure type specified is active and allocation is successful, a lock table 1110 is created with a width as specified by the lock table entry characteristic and a length as specified by the lock table entry count. When the data indicator in the list structure type specified is active and allocation is successful, storage is allocated for the creation of list elements 1214. The size of the list elements 1214 is specified by the list element characteristic. When the adjunct indicator in the list structure type specified is active and allocation is successful, each list entry 1208 created in the structure has an adjunct list entry 1216 with a size of 64 bytes. When the name indicator in the list structure type specified is active and allocation is successful, each list entry 1208 created in the structure has a list entry name associated with it. When the key indicator in the list structure type specified is active and allocation is successful, every user identifier has primary event queue controls associated with it, each list entry 1208 created in the structure has a list entry key associated with it, and each list 1106 has a key range associated with it. The key range list entry key and maximum key range list entry key are both set to zero, and the key range is placed in the empty state. When the secondary key indicator in the list structure type specified is active and allocation is successful, every user identifier has secondary event queue controls associated with it and each list entry 1208 created in the structure has a secondary list entry key associated with it stored in the adjunct list entry 1216. When a list structure 902 is created, (1) the free space and free control space global controls are updated, (2) the appropriate created bit in the structure identifier vector is set to one, and (3) the list structure and list controls 1202 are initialized, including the update of the target structure size and target count objects. When a list structure 902 is created and the maximum structure size request operand 1010 is nonzero, the maximum structure size object is initialized to the largest storage size that the model can support given the structure size and is equal to or smaller than the maximum structure size request operand 1010 rounded up to the nearest integral multiple of the CF storage increment. When a list structure 902 is created, target structure size request operand 1010 is zero, and the maximum structure size request operand 1010 is zero, the maximum structure size object is set equal to the computed target structure size. Specifying a nonzero target structure size which is smaller than the marginal structure size or larger than the maximum structure size will cause the allocation to complete with an appropriate response code. Comparing List Authorities The list authorities are always compared when the write list controls command is executed. Otherwise, the comparison of list authorities is controlled by the list authority comparison type operand. When the value of the list authority comparison type is do not compare, the list authorities are not compared and list authority comparison is successful. When the value of the list authority comparison type is compare for being equal or compare for being less than or equal or when a write list controls command is executed, the CLAU operand is compared with the value of the list authority control in the specified list 1106. The specified list 1106 is designated by the LN operand 1010 in the MCB 1002. The only exception is that when the write and move list entry command results in the creation of a list entry 1208, the specified list 1106 is designated by the TLN operand 1010 in the MCB 1002. When the value of the list authority comparison type is compare for being equal and they are equal, the list authority comparison succeeds, and the command continues. When the value of the list authority comparison type is compare for being less than or equal and the list authority control is less than or equal to the CLAU operand, the list authority comparison succeeds and the command continues. When the list authority comparison fails, command execution is completed with an appropriate response code. Replacing List Authorities The list authority control may be replaced when the write list controls command is executed. Otherwise, the replacement of list authorities is controlled by the list authority replacement type and list authority comparison type operands. When the value of the list authority replacement type is active, the value of the LAU operand is stored in the list authority control provided one of the following conditions exists: The command is write list controls and list authority comparison is successful, and (1) The value of the LAUCT operand is do not compare, or (2) The value of the LAUCT operand is compare for being equal or compare for being less than or equal and list authority comparison is successful. List authority comparison always occurs before any list objects are updated. Comparing Keys When the key comparison type is active, the list entry key object is compared with the list entry key request operand 1010 and optionally the maximum list entry key operand. The key request type operand specifies how the keys are compared. When the secondary key comparison type is active, the secondary list entry key object is compared with the secondary list entry key request operand 1010 and optionally the maximum secondary list entry key operand. The secondary key request type operand specifies how the keys are compared. When both the key comparison type and the secondary key comparison type are active, both key comparisons are performed and both must succeed in order for the key comparison to be successful. For multiple list entry commands, the key comparison is on an entry basis, the key is compared for the entry and the delete, read, or move for the entry occurs if the key comparison is successful for the entry. When the comparison is successful, the list entry 1208 is selectable by a multiple list entry command. When the comparison is unsuccessful, the list entry 1208 is not selectable. Initializing a Key Range A key range is initialized when a write list controls command is executed and the key range list entry key and key range maximum list entry key are updated or when a list 1106 is created and the list 1106 is keyed. A key range is initialized by calculating the number of list entries 1208 in the key range, comparing the count to the key range threshold values, and setting the key range state to either the empty state or the not-empty state. Initialization of the key range can be continued or completed by either continued executions of the write list controls command with bit 7 of the LCT active or by continued execution of the register list monitor command with a monitor request type of key range monitor. If key range initialization is not complete, the WLC or RLM commands complete with appropriate response codes. If key range initialization is not complete, and a WLC command is executed with bit 7 of the LCT inactive or a RLM command is executed and the monitor request type is not key range monitor, then the WLC and RLM commands are executed independently from key range initialization. If the WLC command is executed with bit 7 of the LCT active, key range initialization is in progress, and the specified key range list entry key or key range maximum list entry key are different from the values associated with the key range, initialization of the prior key range is stopped and initialization of the new key range is started. Comparing Global Lock Managers Generally, a global lock manager comparison is performed before a lock table entry 1112 is written, and a global lock manager comparison may be performed before the next nonzero lock table entry 1112 is read, or before a list entry 1208 is created, replaced, read, moved, or deleted, or before an adjunct lock entry is updated by an adjunct locking operation. The global lock manager object is compared with the comparative global lock manager specified. When they match, the global lock manager comparison succeeds. When they do not match, the global lock manager comparison fails. Except for the reset lock managers command and the read next lock table entry command, when a lock table write is to be performed, when a list entry creation, replacement, read, movement, or deletion is to be performed, or when an adjunct lock entry is to be updated by an adjunct locking operation, if the global lock manager comparison is requested and succeeds, the command continues; if the global lock manager comparison is requested and fails, command execution is completed with an appropriate response code. For the reset lock managers command with the unlock type operand set to either B'10' or B'11', if the global lock manager comparison succeeds, the command continues. If the global lock manager comparison fails and if the report mismatch type operand is B'0', then a lock manager mismatch response code is returned. If the global lock manager comparison fails and if the report mismatch type operand is B'1', then the current request block is skipped and the command continues to process the next request block. For the reset lock managers command with the unlock type operand set to B'01', if the global lock manager comparison succeeds and the report mismatch type operand is B'1', or both global and local lock manager comparisons are successful, the command continues. If the global lock manager comparison or local lock manager comparison fails, and the report mismatch type operand is B'0', then a lock manager mismatch response code is returned. If the global lock manager comparison fails and if the report mismatch type operand is B'1', then the current request block is skipped and the command continues to process the next request block. For the read next lock table entry command with the lock request type operand set to compare global lock managers, if the global lock manager comparison succeeds on a nonzero lock table entry 1112, the entry is returned; if the global lock manager comparison fails, the entry is skipped and the scan of the lock table 1110 continues. For the read next lock table entry command with the lock request type operand set to compare global lock or local lock managers, if either global lock manager or local lock manager comparison succeeds on a nonzero lock table entry 1112, the entry is returned; if neither comparison succeeds, the entry is skipped and the scan of the lock table 1110 continues. Comparing Local Lock Managers Generally, local lock manager comparison may occur before a lock table entry 1112 is written, before an adjunct lock entry is updated by an adjunct locking operation, before the next nonzero lock table entry 1112 is read, or before a list entry 1208 is created, replaced, read, moved, or deleted. Local lock manager comparison is also performed as part of the global lock manager replacement process, and may also be performed as part of the local lock manager replacement process. When a local lock manager object exists and a global lock manager replacement is requested, the local lock manager object value is ANDed with a mask of all ones except for the local lock bit corresponding to the user identifier specified. This ANDed value is then compared with zero. When they match, the local lock manager comparison succeeds. When they do not match, the local lock manager comparison fails. When a local lock manager object exists and a local lock manager comparison is requested, or when a local lock manager object exists and a local lock manager replacement that requires the local lock manager comparison to be performed, is requested, the local lock bit corresponding to the user identifier specified is compared with the local lock bit value specified. When (1) they match and local lock manager comparison is requested or (2) they do not match and local lock manager replacement is requested, the local lock manager comparison succeeds. When (1) they do not match and local lock manager comparison is requested or (2) they match and local lock manager replacement is requested, the local lock manager comparison fails. Except for the reset lock managers command and the read next lock table entry command, when a lock table write is to be performed, when a list entry creation, replacement, read, movement, or deletion is to be performed, or when an adjunct lock entry is to be updated by an adjunct locking operation, if the local lock manager comparison is requested and succeeds, the command continues; if the local lock manager comparison is requested and fails, command execution is completed with an appropriate response code. For the reset lock managers command, local lock manager comparison may be performed when the unlock type operand is B'01'. In this case, if the global lock manager comparison succeeds and the report mismatch type operand is B'1', or both global and local lock manager comparisons are successful, the command continues. If the global lock manager comparison or local lock manager comparison fails, and the report mismatch type operand is B'0', then a lock manager mismatch response code is returned. For the read next lock table entry command with the lock request type operand set to compare local lock managers, if the local lock manager comparison succeeds on a nonzero lock table entry 1112, the entry is returned; if the local lock manager comparison fails, the entry is skipped and the scan of the lock table 1110 continues. For the read next lock table entry command with the lock request type operand set to compare global lock or local lock managers, if either global lock manager or local lock manager comparison succeeds on a nonzero lock table entry 1112, the entry is returned; if neither comparison succeeds, the entry is skipped and the scan of the lock table 1110 continues. Locating a List Entry or List Entry Position A list entry 1208 is located by unkeyed position. when an entry locator type of locate by unkeyed position is specified or an unkeyed list entry 1208 is created or moved; that is, the designated position or designated target position is specified by means of a list number and a direction. A list entry 1208 is located by keyed position when the list entries 1208 are keyed and an entry locator type of locate by keyed position is specified or a keyed list entry 1208 is created or moved; that is, the designated position or designated target position is specified by means of a list number, direction, and a list entry key. A list entry 1208 is located by list entry identifier when an entry locator type of locate by list entry identifier is specified; that is, the designated position is the position of the identified list entry 1208. A list entry 1208 is located by list entry name when the list entries 1208 are named and an entry locator type of locate by list entry name is specified; that is, the designated position is the position of the named list entry 1208. A list entry 1208 is located by list cursor position when an entry locator type of locate by list cursor position is specified; that is the designated position is the position of the identified list entry 1208 as specified by the list cursor. A list entry 1208 has a position relative to the designated position or the designated target position. When a list entry 1208 is created, moved, or deleted, the relative positions of the successive list entries 1208 are changed. In these cases, the first entry is the designated list entry 1208 and successive entries are determined by the direction specified. Regardless of how a list entry 1208 is located, when a left-to-right direction is specified, the last entry is the rightmost entry in the list 1106, and when a right-to-left direction is specified, the last entry is the leftmost entry in the list 1106. Designated List Entry The designated list entry 1208 is (1) the first entry relative to the designated position before an entry is deleted, moved, read, replaced, replaced and moved, moved and read, or read and deleted, or is (2) the first entry relative to the designated target position after an entry is created. When a list entry 1208 is located by list entry identifier, the designated list entry 1208 is the identified list entry 1208. When a list entry 1208 is located by list entry name, the designated list entry 1208 is the named list entry 1208. When a list entry 1208 is located by list cursor position, the designated list entry 1208 is the identified list entry 1208 as specified by the list cursor. When a list entry 1208 is located by unkeyed position and a left-to-right direction is specified, the designated list entry 1208 is the leftmost entry in the list 1106. When a list entry 1208 is located by unkeyed position and a right-to-left direction is specified, the designated list entry 1208 is the rightmost entry in the list 1106. When (1) a list entry 1208 is located by keyed position the entry locator key type is primary, and the KRT does not indicate key range, (2) entry deletion, read, replacement, or movement is requested, (3) a list entry 1208 with an equal key, a less than or equal key, or a greater than or equal key, exists on the list 1106, depending on the key request type, and (4) a left-to-right direction is specified, then the designated list entry 1208 is the leftmost entry with a key equal, with the largest key less than or equal, or with the smallest key greater than or equal to the specified list entry key request operand 1010.
When (1) a list entry 1208 is located by keyed position, the entry locator key type is secondary, and the SKRT does not indicate key range, (2) entry deletion, read, replacement, or movement is requested, (3) a list entry 1208 with an equal secondary key, a less than or equal secondary key, or a greater than or equal secondary key, exists on the list 1106, depending on the secondary key request type, and (4) a right-to-left direction is specified, then the designated list entry 1208 is the rightmost entry with a secondary key equal, with the largest secondary key less than or equal, or with the smallest secondary key greater than or equal to the specified secondary list entry key request operand 1010. When (1) a list entry 1208 is located by keyed position, the entry locator key type is primary, and the KRT indicates key range, (2) entry deletion, read, replacement, or movement is requested, (3) a list entry 1208 with a key within range exists on the list 1106, and (4) a left-to-right direction is specified, then the designated list entry 1208 is the leftmost entry with a key value greater than or equal to the specified list entry key request operand 1010. When (1) a list entry 1208 is located by keyed position, the entry locator key type is primary, and the KRT indicates key range, (2) entry deletion, read, replacement, or movement is requested, (3) a list entry 1208 with a key within range exists on the list 1106, and (4) a right-to-left direction is specified, then the designated list entry 1208 is the rightmost entry with a key value less than or equal to the specified maximum list entry key request operand 1010. When (1) a list entry 1208 is located by keyed position, the entry locator key type is secondary, and the SKRT indicates key range, (2) entry deletion, read, replacement, or movement is requested, (3) a list entry 1208 with a secondary key within range exists on the list 1106, and (4) a left-to-right direction is specified, then the designated list entry 1208 is the leftmost entry with a secondary key value greater than or equal to the specified secondary list entry key request operand 1010. When (1) a list entry 1208 is located by keyed position, the entry locator key type is secondary, and the SKRT indicates key range, (2) entry deletion, read, replacement, or movement is requested, (3) a list entry 1208 with a secondary key within range exists on the list 1106, and (4) a right-to-left direction is specified, then the designated list entry 1208 is the rightmost entry with a key value less than or equal to the specified maximum secondary list entry key request operand 1010. Designated Position The designated position is the position of the designated list entry 1208 before an entry is moved, deleted, read, replaced, replaced and moved, moved and read, or read and deleted. The designated position is specified (1) by an unkeyed position, (2) by a keyed position, (3) by a list entry identifier, (4) by a list entry name, or (5) by a list cursor, depending on the entry locator type and the entry locator key type specified and the type of structure allocated. When a list entry 1208 is located by list entry identifier or by list entry name, the designated position exists when the list entry 1208 exists. When a list entry 1208 is located by list cursor, the designated position exists when the identified list entry 1208 exists as specified by the list cursor. When a list entry 1208 is located by unkeyed position, the designated position exists when the list 1106 exists and there is at least one entry on the list 1106. When a list entry 1208 is located by keyed position and entry creation is not requested, the designated position exists when a list entry 1208 in the list 1106 has a key that is equal, greater than or equal, or less than or equal to the specified list entry key in the list 1106, depending on the key request type. When a list entry 1208 is located by keyed position, the entry locator key type is primary, and entry creation is not requested, the designated position exists when a list entry 1208 in the list 1106 has a key that is equal to, greater than or equal to, less than or equal to, or within the range specified by the list entry key and the maximum list entry operands, depending on the key request type. When a list entry 1208 is located by keyed position, the entry locator key type is secondary, and entry creation is not requested, the designated position exists when a list entry 1208 in the list 1106 has a secondary key that is equal to, greater than or equal to, less than or equal to, or within the range specified by the secondary list entry key and the maximum secondary list entry operands, depending on the secondary key request type. When the designated position does not exist, an appropriate response code is returned. Designated Target Position The designated target position is the position of the designated list entry 1208 after an entry is created or moved. The designated target position is specified (1) by an unkeyed position or (2) by a keyed position, depending on the type of structure allocated. When a list entry 1208 is located by unkeyed position and a left-to-right direction is specified, then the designated target position is the leftmost position in the list 1106. When a list entry 1208 is located by unkeyed position and a right-to-left direction is specified, then the designated target position is the rightmost position in the list 1106. When (1) a list entry 1208 is located by keyed position, (2) entry creation or movement is requested, (3) a list entry 1208 with an equal key of the specified entry locator key type exists on the list 1106, (4) a left-to-right direction is specified, then the designated target position is the position of the leftmost entry with the same key. When (1) a list entry 1208 is located by keyed position, (2) entry creation or movement is requested, (3) a list entry 1208 with an equal key of the specified entry locator key type exists on the list 1106, (4) a right-to-left direction is specified, then the designated target position is the position of the rightmost entry with the same key. When (1) a list entry 1208 is located by keyed position, (2) entry creation or movement is requested, and (3) all entries on the list 1106 have a key of the specified entry locator key type greater than the specified key, the designated target position is the leftmost position in the list 1106. When (1) a list entry 1208 is located by keyed position, (2) entry creation or movement is requested, (3) at least one list entry 1208 on the list 1106 has a key of the specified entry locator key type less than the specified key, and (4) there is no list entry 1208 in the list 1106 that matches the specified key, then the designated target position is the first position after the rightmost entry with a key less than the specified list entry key in the list 1106. When a list entry 1208 is located by keyed position and entry creation or movement is requested, the designated target position exists when the list 1106 exists. Comparing List Numbers When the list number comparison type is active and a list entry 1208 is not created, a list number comparison is requested. When list number comparison is requested, the list number object is compared with the list number specified. If they do not match, the list number comparison fails, command execution is completed with an appropriate response code or command execution continues by skipping the current list entry 1208, depending on the command. Comparing Counts There are four sets of counts that are compared, depending on the process requested: the list set entry counts, the list set element counts, the event monitor controls counts, and the list entry counts or list element counts, depending on the element count indicator. Comparing Event Monitor Controls Counts The maximum event monitor controls count object is compared with the event monitor controls count object whenever an event monitor is registered and event monitor controls creation is requested. The event monitor controls object space is full when the maximum event monitor controls object equals the event monitor controls object. Comparing List Element Counts The list element count limit object is compared with the list element count object whenever a list entry 1208 is written or moved, the suppress list limit comparison control is inactive, and the element count indicator in the list structure type is active. If the sum of the list element count and the number of additional list elements 1214 required exceeds the list element count limit, the list 1106 is full. When the list 1106 is full and a write or move operation is requested, an appropriate response code is returned. The list element count limit or list entry count limit is updated on a write list controls command, depending on the list control type. Comparing List Entry Counts The list entry count limit object is compared with the list entry count object whenever a list entry 1208 is created or moved, the suppress list limit comparison control is inactive, and the element count indicator in the list structure type is inactive. A list 1106 is full when the number of list entries 1208 created matches or exceeds the list entry count limit. When the list 1106 is full and a create or move operation is requested, an appropriate response code, depending on the command, is returned. The record global lock manager command is an exception to list entry count limit comparison. Comparing List Set Element Counts The maximum list set element count object is compared with the list set element count object whenever a data list entry 1212 is written. If the sum of the list set element count and the number of additional list elements 1214 required exceeds the maximum list set element count, the list set 1104 is full. When the list set 1104 is full, and list entry creation or replacement, or retry data block creation is requested, an appropriate response code is returned. Comparing List Set Entry Counts The maximum list set entry count object is compared with the list set entry count object whenever a list entry 1208 is created. A list set 1104 is full when the number of list entries 1208 created and not deleted matches the maximum list set entry count. When a list set 1104 is full and list entry creation is requested, an appropriate response code, depending on the command, is returned. Updating Counts There are three types of counts that are updated, depending on the process requested: the list s | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||