If the user codes ACCESSTIME=MAXIMUM, the maximum time that serialization is held is determined by the first connection that allocates the structure with the value specified for MAXTIME.

If the user codes ACCESSTIME=NOLIMIT, serialization is held for as long as it is required to capture the data from SVC dump or until the structure dump or its serialization would be forced with either the IXLFORCE macro or the SETXCF FORCE command.

ACCESSTIME is set by the first connector to the structure. In the IXLYCONA answer area, the fields CONAACCESSTIME AND CONAACCESSTIMENOLIMIT contain the values pertinent to the allocation of the structure.

DEFAULT

The request can be used to allocate the structure, if necessary. This is intended to only be used as a default - not actually specified on the IXLCONN invocation.

NO

The request should not be used to allocate the structure. If the structure is not allocated, the request will fail with IXLRSNCODESTRNOTALLOCATED.

When ALLOC=NO is specified, IXLCONN parameters that are only used for structure allocation are ignored. The following IXLCONN parameters are ignored:

• STRSIZE
• STRDISP
• ACCESSTIME
• MAXTIME
• CONNECTIVITY

With the exception of STRDISP, ignored parameters do not need to be specified.

When running on a system without support for the ALLOC key, specifying ALLOC will cause the request to fail with different reason codes depending upon the structure type:

TYPE=CACHE

IXLRSNCODEINVALIDSTGCLASS

TYPE=LIST

IXLRSNCODENOLISTHDRS

TYPE=LOCK

IXLRSNCODENOLENTRIES

The structure alter procedure is done in place on the previously allocated structure. Structure alter provides a non-disruptive alternative to rebuild for changes to be made to the structure. Changes other than those listed, such as changing the location of a structure, must be accomplished with the rebuild function.

The MINENTRY, MINELEMENT, and MINEMC parameters are used when a structure alter is initiated to contract a structure or reapportion its ratio and/or its EMC storage, where that request would decrease the amount of storage available for entries, elements, or EMCs. These values prevent a structure alter from making a structure unusable to the application, as might occur if more free entries, elements, or EMC storage were removed or reallocated than the application could tolerate. If a structure alter tries to contract or reapportion more free space than specified by the MIN parameters, the alter will be stopped. The MIN values are not used during requests to expand the structure, or during reapportion requests which increase the amount of storage available for a particular storage type.

NO

Indicates that this connection does not support system-managed processes. An application that does not support structure rebuild (ALLOWREBLD=NO) and specifies or defaults to ALLOWAUTO=NO must provide its own support for planned reconfiguration of the coupling facility. The planned reconfiguration support might include normal shutdown procedures or an operator command interface. The application support must allow the operator to stop an application's use of a structure in a coupling facility.

YES

Indicates that this connection supports system-managed processes. The application support for system-managed processes includes the following:

• Processing the Structure Temporarily Unavailable and Structure Available events.
• Using extended restart tokens.
• Evaluating the information presented with the Structure State Change event and reacting appropriately to changes in structure characteristics.
• Using both physical structure version numbers to uniquely identify an instance of a structure. (In IXLYCONA, the physical version numbers are identified by CONAPHYSICALSTRUCTUREVERSION and CONAPHYSICALSTRUCTUREVERSION2; in IXLYEEPL, the physical version numbers are identified by EEPLSSCSTRPHYSICALVERSION and EEPLSSCSTRPHYSICALVERSION2).

If any active or failed-persistent connection to the structure specified ALLOWDUPREBLD=NO, the system will reject a request to start duplexing the structure.

When a duplexing rebuild is in progress, if any new request to connect to the structure specifies ALLOWDUPREBLD=NO, the system will reject the connection request.

Duplexing rebuild allows connectors to a structure to allocate another structure with the same name as the original structure. It allows connectors to duplex data into both structures. Use the duplexing rebuild procedure for improved availability and usability

If any active connection to the structure specified ALLOWREBLD=NO and specified or defaulted to ALLOWAUTO=NO, the system will reject a request to start rebuilding the structure.

If all active connections specified or defaulted to ALLOWREBLD=YES, the specification of ALLOWAUTO is not considered.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword output field that identifies the answer area.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword input field that contains the length of the answer area.

Do not request a level based on whether the connector supports system-managed processes (ALLOWAUTO keyword). It is neither necessary nor desirable to request the CFLEVEL required by a particular system-managed process simply because ALLOWAUTO=YES is specified. (For example, do not specify CFLEVEL=8 for the purpose of supporting system-managed rebuild.) If you specify ALLOWAUTO=YES, the system will automatically attempt to allocate your structure in a coupling facility that supports system-managed processes. Therefore, your CFLEVEL specification should reflect only the level required for the requests that you expect to submit against the structure.

On a successful connect, the field CONACFACILITYCFLEVEL indicates the level of operations that can be performed against the structure. CONAMVSRELEASEMAXCFLEVEL indicates the level of operations supported by the operating system on which the connector is running. These coupling facility levels can differ from the requested level, so the connector must verify that the level returned is suitable for its use. The connector must not issue operations that require a coupling facility level greater than the lower of CONAMVSRELEASEMAXCFLEVEL and CONACFACILITYCFLEVEL.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword input field that contains the level of coupling facility required.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the complete exit for the requestor.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 8-character input field that contains the connector data.

KEEP

Indicates that the connection to the structure is to be placed in a failed-persistent state. Peer connectors, notified of the Disconnected/Failed Connection event through their event exits, must respond either with the event exit return code or IXLEERSP.

After all peer connectors have responded to the event, XES uses the CONDISP specification to determine whether to make the connector be failed-persistent or not defined. If peer connectors were able to recover for the failing user, they may override the CONDISP=KEEP parameter to indicate that the connector does not need to be made failed-persistent.

Once a connector is placed in a failed-persistent state, the failed connector can try to reconnect to the structure by reissuing IXLCONN with the same CONNAME specified on the original IXLCONN macro. (See CONNAME.)

If the user is unable to reconnect or chooses not to do so, the following options exist to delete the failed-persistent connection:

• The operator or extended MCS console interface can issue the SETXCF FORCE command to delete the connection.
• A connected user or authorized program can issue the IXLFORCE macro to delete the connection.

DELETE

Indicates that the connection to the structure is to be put in the not-defined state after the requestor disconnects or terminates abnormally. Prior to being placed in the not-defined state, peer connectors must have been notified of the Disconnected/Failed Connection event and have responded to confirm the failure.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-character input field to contain the connector's processing level.

The connection name must be 16 characters long, padded on the right with blanks, if necessary. The name can contain numeric characters, uppercase alphabetic characters, national characters ($, @, #), or an underscore (_). Connection names must begin with an uppercase alphabetic character or a national character.

Connection names must be unique for each user connected to a structure. If CONNAME for the request matches the name of another active connection, the system rejects the request.

CONNAME is required for CONDISP=KEEP. To reconnect, a requestor can issue IXLCONN with CONNAME. If the CONNAME matches the name of the failed-persistent connection, then the connector will be reconnected. When a requestor reconnects to the structure, the system returns a new connect token to the connect answer area and sets return code X'4' that the user has reconnected. A reason code of IXLRSNCODESPECIALCONN also is returned to indicate that the connector should examine IXLYCONA to be aware of any changes that might have been made on the reconnect.

CONNAME is optional for CONDISP=DELETE. If a user does not specify CONNAME, the system generates a name. Note however, that CONNAME must be specified when IXLCONN REBUILD is issued, even if CONDISP=DELETE. CONNAME must match the connection name returned in IXLYCONA for the original connection.

If an event that the system reports to the event exit is about a connection to the structure, the system reports the connection's CONNAME to the event exit of all connected users.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 16-character field that contains the unique connection name to identify the user request.

For a connector to a serialized structure (TYPE=LOCK or TYPE=LIST with LOCKENTRIES), XES invokes IXCJOIN on behalf of the connector to define an XCF group member for the connector and the CRITICAL attribute will be propagated to the IXCJOIN invocation. If the critical XCF group member appears to be impaired for too long, XCF will terminate the impaired member according to the TERMLEVEL specification.

See the CRITICAL keyword description on the IXCJOIN macro (IXCJOIN — Place an XCF Member in the Active State) for additional information about critical XCF group members.

NO

Indicates that the connector does not designate itself as a critical connector.

YES

Indicates that the connector designates itself as a critical connector. For serialized structures (TYPE=LOCK or TYPE=LIST with LOCKENTRIES), XCF will monitor the health of the XCF group member that was defined on behalf of the connector. If the member becomes impaired for too long, XCF will terminate the member according to the TERMLEVEL specification.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the event exit for the requestor.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 24-character input field that contains the description of the function, service, or application associated with the connector. The string can contain any alphanumeric (A-Z), national (@,#,$), or special character (underscore or blank). Leading blanks and all blank descriptors are not permitted.

or ALLOC=NO

NO

Indicates that rebuild connect processing is to use the parameter list to determine the structure allocation attributes related to structure object ratios.

YES

Indicates that rebuild connect processing is to use the current (old structure) attributes to determine the structure allocation attributes related to structure object ratios. When the system has support for this keyword (APAR OA33448), IXLCONN parameters that determine structure allocation attributes related to structure object ratios are to be ignored.

For list structures, the following IXLCONN parameters are ignored:

• ENTRYRATIO
• ELEMENTRATIO
• EMCSTGPCT
• LISTCNTLTYPE
• KEYTYPE
• REFOPTION
• ADJUNCT
• MAXELEMNUM
• ELEMCHAR
• ELEMINCRNUM.

For cache structures, the following IXLCONN parameters are ignored:

• DIRRATIO
• ELEMENTRATIO
• MAXELEMNUM
• ELEMCHAR
• ELEMINCRNUM.

When running on a system at z/OS® V1R12 or earlier, use the ignored parameters as you normally would in case the system does not have support for the keyword. For a z/OS V1R12 system or later, with the keyword support you do not need to specify the ignored parameters. In addition to maintaining current structure object ratios, KEEPRATIOS=YES might also make it more likely for equivalent structure object counts to be achieved

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the halfword input field that contains the length of time that SVC dump holds serialization for the structure when the user specifies ACCESSTIME=MAXIMUM.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

The value specified by MINCFLEVEL must be equal to or less than the value specified by CFLEVEL.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword field that contains the minimum CFLEVEL requested.

When the specified minimum level is attained, IXLALTER processing will end. If the minimum level cannot be attained, IXLALTER processing will provide a percentage of available elements as close to the target level as possible.

The value of MINELEMENT must be in the range of from 0 to 100.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the one-byte field that contains the percent value.

When the specified minimum level is attained, IXLALTER processing will end. If the minimum level cannot be attained, IXLALTER processing will provide a percentage of available EMCs as close to the target level as possible.

The value of MINEMC must be in the range of 0 to 100, inclusive.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the one-byte field that contains the percent value.

When the specified minimum level is attained, IXLALTER processing will end. If the minimum level cannot be attained, IXLALTER processing will provide a percentage of available entries as close to the target level as possible.

The value of MINENTRY must be in the range of from 0 to 100.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the one-byte field that contains the percent value.

The nonvolatility attribute refers to the ability of certain coupling facilities to maintain their stored data should a power outage occur.

The failure-independent attribute refers to the configuration of a coupling facility in an independent failure domain from the MVS™ systems that access it. An independent failure domain ensures that there is not a single point of failure.

YES

Indicates that this connection does allow changes to the entry-to-element ratio and the EMC storage percentage when a structure alter is initiated by an IXLALTER request. When specifying RATIO=YES, you must also specify ALLOWALTER=YES and CFLEVEL=1 or higher.

NO

Indicates that this connection does not allow changes to the entry-to-element ratio and the EMC storage percentage when a structure alter is initiated by an IXLALTER request.

Specifying RATIO=NO does not mean that the entry to element ratio cannot change. It may change as a result of a structure size change, or if the actual structure size (CONASTRUCTURESIZE) is less than the minimum control space (CONAMINSTRUCTURESIZE) required to allocate the structure with the attributes specified.

Once the new structure has been allocated, REBUILD requests from subsequent users connect the users to the new structure. As with any request to connect to a structure, the connectors must check the connect answer area to determine the actual attributes of the structure.

REBUILD requests must be issued from the same address space and from the same system as that from which the original IXLCONN macro for the structure was issued. REBUILD requests can be issued from a task other than the task that issued IXLCONN for the original structure.

CONNECT

Can be used for normal (original) or rebuild connect requests but should only be used for normal connect requests. This is intended only to be used as the default and not actually specified on the IXLCONN invocation.

REBUILDCONNECT

Indicates a rebuild connect is requested. The rebuild process allows you to allocate another structure with the same name and to reconstruct data, if applicable, in the newly allocated structure. The rebuild process is intended for planned reconfiguration and recovery scenarios and requires established protocols to ensure an orderly transition from the old to the new structure.

The requestor must be connected to the original structure that is the target of the rebuilding process. If the rebuilding process for the structure has not been initiated (through the SETXCF START,REBUILD command or the IXLREBLD macro), the system rejects the rebuild connect request.

If rebuild has been initiated but the new structure has not been allocated, the rebuild connect request allocates the new structure. With this parameter, you must specify the same name (STRNAME) as that of the original structure. You can also modify the following IXLCONN parameters according to the structure TYPE:

For a cache structure:

ADJUNCT	MAXELEMNUM1	VECTORLEN
ELEMENTRATIO	UDFORDER	ELEMCHAR1
NUMSTGCLASS	DIRRATIO1	NUMCOCLASS
CONNECTIVITY	NAMECLASSMASK
Note: The parameter is ignored by a system with APAR OA33448 installed when KeepRatios=YES is specified.

For a list structure:

ADJUNCT1	ENTRYRATIO1	REFOPTION1
EMCSTGPCT1	MAXELEMNUM1	ELEMENTRATIO1
LOCKENTRIES	ELEMCHAR1	LISTHEADERS
CONNECTIVITY	LISTCNTLTYPE1	VECTORLEN
Note: The parameter is ignored by a system with APAR OA33448 installed when KeepRatios=YES is specified.

For a lock structure:

CONNECTIVITY
LOCKENTRIES
NUMUSERS1
Note: The value must be equal to or greater than the value for the original structure.

The following keywords will be IGNORED for rebuild connect requests:

• CFLEVEL
• CONTEXIT
• NOTIFYEXIT
• LISTTRANEXIT.

Note that some of these keywords are required, and you must therefore specify them for rebuild connect requests.

If the new structure for rebuild has not yet been allocated, then IXLCONN will allocate a new structure with the same name and using the attributes specified on connect. This connection will be connected to the new structure allocated for rebuild. As with any request to connect to a structure, the connectors must check the connect answer area to determine the actual attributes of the structure.

The rebuild connect request must be issued from the same address space and same system as the original IXLCONN which connected this user to the structure.

The rebuild connect request can be issued from a task other than the connecting task.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword to contain the return code.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword to contain the reason code.

KEEP

Indicates that the structure remains allocated after all connectors have disconnected from the structure. You can delete a structure with this disposition with the IXLFORCE macro, the IXLDISC macro with the DELETESTR keyword, or the SETXCF FORCE operator command.

DELETE

Indicates that the structure is deleted from the coupling facility after all connectors (including failed-persistent connections) have disconnected from the structure.

The structure name must be 16 characters long, padded on the right with blanks, if necessary. The name can contain numeric characters, uppercase alphabetic characters, national characters ($, @, #), or an underscore (_). Structure names must begin with an uppercase alphabetic character. IBM structure names begin with SYS, an IBM component prefix, and the letter A through I.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the 16-character input field that contains the structure name.

• If the size specified is smaller than the minimum structure size that is specified or defaulted to in the active CFRM policy (MINSIZE), the system uses the MINSIZE value as the size of the structure.
• If the size specified is smaller than the structure size defined in the active CFRM policy (SIZE), the system uses the strsize value. The strsize is bounded by MINSIZE and SIZE in the active CFRM policy.
• If the size specified is larger than the structure size defined in the active CFRM policy, the system uses the size defined in the active policy (SIZE from policy).
• If you use the default value of zero for strsize, the system uses the size defined in the active CFRM policy (INITSIZE, if specified, or SIZE).

Note that in all cases, if there are limited coupling facility resources available, the system might allocate the structure using less space than was requested. MINSIZE specified in the active CFRM policy will serve as a minimum bound for the structure on all structure allocation requests (including alter, connect, and rebuild connect) except for new structure allocation during System-managed rebuild. New structure allocation during System-managed rebuild may cause the structure to be allocated with a size smaller than MINSIZE in the active CFRM policy. The actual structure size allocated is returned in field CONASTRUCTURESIZE in the IXLYCONA answer area. The requested structure size is returned in field CONAALLOCREQUESTEDSTRSIZE in IXLYCONA.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of the fullword input field that contains the number of 4K blocks to make up the structure.

• Suspend work units that issue coupling facility requests against a structure while it is undergoing a system-managed process (for example, rebuild), regardless of the MODE specified on the coupling facility request.
• Process such requests as indicated by the MODE specification of the request.
• Fail such requests.

The SUSPEND keyword does not affect coupling facility requests that specify MODE=SYNCFAIL or MODE=SYNCSUSPEND.

YES

Indicates that the system will, when possible, override a request's MODE specification and suspend the requestor while the structure is quiesced during a system-managed process. Specifying SUSPEND=YES permits the system to limit the number of incoming requests by quiescing the work units that would otherwise be submitting them. This minimizes the system resources required to quiesce activity against the structure undergoing the system-managed process.

When the requestor is suspended as the result of specifying SUSPEND=YES, the duration of the suspend depends on the request:

• For cache (IXLCACHE) requests and unserialized list (IXLLIST, IXLLSTC, IXLLSTE, IXLLSTM) requests, the requestor's unit of work will be resumed when the request is complete.
• For IXLLOCK and serialized list (IXLLIST, IXLLSTC, IXLLSTE) requests, the requestor's unit of work will be resumed as soon as the quiesce for the system-managed process is complete. If the request subsequently encounters contention, control will be returned to the requestor's unit of work with the appropriate return code to indicate that the request will be completed asynchronously.

When the requestor is resumed after being suspended as the result of specifying SUSPEND=YES, the system will notify the requestor of request completion as follows:

• For cache (IXLCACHE) requests, IXLLOCK requests that do not encounter contention, unserialized list (IXLLIST, IXLLSTC, IXLLSTE, IXLLSTM) requests, and serialized list (IXLLIST, IXLLSTC, IXLLSTE) requests that do not encounter contention:
  • If the MODE requested that the system attempt to complete the request synchronously (for example, SYNCEXIT), the requestor will receive a return code indicating synchronous completion once the process completes.
  • If the MODE requested asynchronous processing (for example, ASYNCEXIT), the requestor will receive a return code indicating asynchronous completion, and the requestor will be notified of the results of the request through the specified mechanism (for example, the Complete exit).
• For IXLLOCK and serialized list (IXLLIST, IXLLSTC, IXLLSTE) requests that encounter contention and can tolerate asynchronous completion (for example, not SYNCSUSPEND):
  • The requestor will receive the appropriate return code indicating asynchronous completion, and will be notified of the results of the request through the mechanism corresponding to the MODE specification once contention is resolved.

NO

Indicates that the connector cannot tolerate suspension of units of work submitting coupling facility requests except as specified on the MODE keyword of list (IXLLIST, IXLLSTC, IXLLSTE, IXLLSTM), cache (IXLCACHE), and IXLLOCK requests, and will therefore use suspend/resume processing only on units of work that specify MODE=SYNCSUSPEND. The system will quiesce all other activity by deferring requests internally until the system-managed process completes.

FAIL

Indicates that the connector cannot tolerate the potentially long-term suspension or delay of units of work submitting coupling facility requests while the structure is quiesced for system-managed processing. Requests which cannot be immediately processed due to the structure being quiesced for system-managed processing will be failed. Such requests will neither be deferred internally for asynchronous processing, nor will the requesting unit of work be suspended. If the structure is quiesced to fall out of a system-managed duplexing rebuild, which is only a short-term delay, then the request will be processed as if SUSPEND=NO had been specified. SUSPEND=FAIL is not applicable to lock or serialized list structures. Connect attempts to these types of structures will fail if SUSPEND=FAIL is specified.

• To relieve a hang in a subsequent process related to the structure to which the invoker is connecting. The system will take automatic action if the hang is caused by failure of a connector to provide an expected response, and if the installation has specified a nonzero CFSTRHANGTIME value in the SFM policy. The TERMLEVEL keyword does not affect applicable hang relief actions that are not specific to a connector, such as stopping a rebuild.
• In response to an unexpected error while processing a coupling facility request initiated by the connector or during other processing associated with such a request.

TERMLEVEL=TASK

When termination of this connector is required, the system’s first level of response will be to terminate the task from which the IXLCONN macro was issued. This is the default level, and should be used unless the application cannot tolerate task termination.

TERMLEVEL=ADDRSPACE

When termination of this connector is required, the system’s first level of response will be to terminate the home address space from which the IXLCONN macro was issued. This level should be selected only if failure of the connector’s task will leave sysplex resources in an unusable condition or for some other reason cannot be tolerated.

Task-level recovery is permitted to run when the connector's address space is terminated as a result of this selection.

TERMLEVEL=SYSTEM

When termination of this connector is required, the system’s first level of response will be to partition the connector’s system. This level should be selected only if failure of the connector’s task or address space will leave sysplex resources in an unusable condition or for some other reason cannot be tolerated.