gtpd1m30Database Reference

Connecting to a Coupling Facility Structure

You connect to a CF structure to use connection services to manage data in that CF structure. See Connection Services for more information about connection services.

Overview of Connect Processing

You connect to a CF structure to manage structure data. The first TPF system to connect to a CF structure causes the structure to be allocated in a CF using the structure attributes specified on the CFCONC macro. Subsequent connectors to the CF structure cannot change those initial structure attributes. The number of TPF systems that are allowed to connect to a CF structure is a function of the CF model.

Once your CFCONC request is completed successfully:

Specifying Structure Attributes for Coupling Facility Structures

The following CFCONC parameters define the structure attributes for the CF structure. See the CFCONC macro in TPF System Macros for detailed information about each parameter.

Parameters Common to Both Structure Types

Parameter
Description

 CFLEVEL 
Use this parameter to specify the level of the CF in which the CF structure will be allocated. If you try to connect with a CF level higher than that of the CF, your CFCONC request fails with return code ICFRRCBADCFLEVEL. The maximum CF level value supported is returned in the CFCONC answer area in the ICFCAATPFMAXCFLEV field. The CF level in which the CF structure is actually allocated is returned in the ICFCAACFLEVEL field.

The CF level can be specified only through the CFCONC macro. To change to a different CF level, you must disconnect and then connect to the CF structure again with a different value.

See Coupling Facility Considerations and Disconnecting from a Coupling Facility Structure for more information.

 CFNAME 
Use this parameter to specify the CF name, which is needed to allocate the CF structure.

 CONDATA 
Use this parameter to provide 8 bytes of connect data. The CF passes this data to your exit routines when called and is for your use only. A possible use for this parameter is as a pointer to a control block that represents the connector.

 CONNAME 
Use this parameter to identify your connection to the CF structure.

 STRNAME 
Use this parameter to name the CF structure to which you want to connect. You must supply this name to users of your application and then use the TYPE parameter to indicate that the structure you want allocated is a CF list structure or a CF cache structure.

 STRSIZE 
Use this parameter to specify the size of the CF structure in 4-KB blocks.

 STRDISP 
Use this parameter to specify the disposition of the CF structure when all connections are released.

 TYPE 
Use this parameter to identify the type of CF structure in the CF to which you want to connect. For a CF list structure, the type is LIST. For a CF cache structure, the type is CACHE.

Parameters for CF List Structures

Parameter
Description

 ADJUNCT 
Use this parameter to specify whether the CF list structure will contain adjunct data areas.

 ELEMCHAR 
Use this parameter to specify the data element size to be used.

 ELEMENTRATIO 
Use this parameter to specify the element component of the entry-to-element ratio.

 ELEMINCRNUM 
Use this parameter to specify the data element size to be used.

 ENTRYRATIO 
Use this parameter to specify the list entry portion of the entry-to-element ratio.

 LISTCNTLTYPE 
Use this parameter to specify whether the amount of CF storage that may reside on a given list header is to be controlled by limiting the maximum number of entries or the maximum number of data elements.

 LISTHEADERS 
Use this parameter to specify the number of lists to be allocated in the CF list structure.

 LISTTRANEXIT 
Use this parameter if you plan to use list monitoring because the parameter specifies the address of your list transition exit routine.

 LOCKENTRIES 
Use this parameter to specify the number of lock entries for a serialized CF list structure.

 MAXELEMNUM 
Use this parameter to specify the maximum number of data elements for each data entry.

 REFOPTION 
Use this parameter to specify whether list entries are to be referenced by entry name, entry key, or neither. List entries can always be referenced by the list entry identifier (LEID) or unkeyed position.

 VECTORLEN 
Use this parameter if you plan to use list monitoring because the parameter specifies the maximum number of list headers that you can monitor for transitions between empty state and nonempty state.

Parameter for CF Cache Structures

Parameter
Description

 VECTORLEN 
Use this parameter to specify the number of cache buffers in the local storage of the requester that require concurrent registration.

Determining Whether a Connection Is Successful

When you issue the CFCONC macro, you identify the storage area (using the ANSAREA parameter) where the TPF system returns information about the success or failure of your connect request. Note the following about the return codes shown in Table 18 and Table 19:

If your request to connect to a CF structure is successful, one of the following return codes, as shown in Table 18, is returned.

Table 18. Return Codes for a Successful Connection to a CF Structure

Return Code Equate Symbol Description
0000 ICFRRCOK Your connection is successful. The TPF system has returned data to you in the CFCONC answer area.
0004 ICFRRCWARNING Your connection is successful, but you may need to do additional processing based on the information returned to you in the CFCONC answer area.

If your request to connect to a CF structure is not successful, one of the following return codes, as shown in Table 19, is returned in R15.

Table 19. Return Codes for an Unsuccessful Connection to a CF Structure

Return Code Equate Symbol Description
0008 ICFRRCPARMERROR You have incorrectly specified a parameter on your CFCONC request.
000C ICFRRCENVERROR There is an environmental error.
0010 ICFRRCCOMPONENT A system failure occurred.

See Receiving Information in the CFCONC Answer Area for more information.

Receiving Information in the CFCONC Answer Area

When you issue the CFCONC macro, you identify the storage area where the TPF system will return information about the status of your request. Use the following parameters to specify this CFCONC answer area:

Parameter
Description

 ANSAREA 
Contains the address of the CFCONC answer area. Use the ICFCAA DSECT to map the CFCONC answer area.

 ANSLEN 
Contains the length of the CFCONC answer area. The length must be large enough to hold the CFCONC answer area mapped by the ICFCAA DSECT.

Successfully Completing a Connection

The CFCONC macro returns information about a successful connection in the ANSAREA area. See the ICFCAA DSECT for information about the successful completion of a connection.

Handling Failed Attempts to Connect to a Coupling Facility Structure

When a connection request is not successful, you must consider the conditions that could have caused the rejection. In a short-term condition, consider issuing the connect request again as soon as possible.

Another type of condition may require your intervention and, therefore, take a significantly greater amount of time to resolve. It may be necessary to reconfigure connectivity to a CF. The following are examples of longer-term conditions that cause a connect request to fail: