gtps1m1pSystem Macros

CFCONC-Connect to a Coupling Facility List or Cache Structure

Use this system macro to allocate and connect to a coupling facility (CF) list or cache structure on a CF, or to connect to a CF list or cache structure that is allocated already. A CF list or cache structure is a named piece of storage on a CF.

The first user to connect to a CF list or cache structure allocates the structure on a CF and defines the structure attributes, including the type of CF structure (list or cache). Other users can connect to the CF structure by name, but cannot change the structure attributes of the CF structure as long as it remains allocated. All connectors, whether the first or subsequent, are informed of the structure attributes through the CFCONC answer area, which is mapped by the ICFCAA DSECT. Users are responsible for checking the structure attributes to verify that they are acceptable.

See TPF Database Reference for more information about connecting to a CF list or cache structure.

Format




Parameters Common to Both Structure Types

CFNAME=cfname
Specifies the CF name, which is needed to allocate the CF list or cache structure. The CF name must be a 5- to 8-character alphanumeric name, and the first character must be an alphabetic character.

To code, specify the name or address of the 8-character field that contains the CF name in which the CF list or cache structure is to be allocated.

STRNAME=strname
Specifies the name of the CF list or cache structure to which you want to connect. The name you specify must meet the following requirements:

To code, specify the name or address of the 16-character input field that contains the CF list or cache structure name.

STRSIZE=strsize
Specifies the size of the CF list or cache structure in 4-KB blocks. This is a required parameter.
Note:
If there are limited CF resources available, the CF list or cache structure can be allocated with less space than you requested. The actual size of the CF list or cache structure allocated is returned in the ICFCAASTRSIZE field of the CFCONC answer area.

To code, specify the name or address of the fullword input field that contains the number of 4-KB blocks that make up the CF list or cache structure.

CONDATA
Specifies the connect data to pass to your exit routines, where:

ALL_ZEROS
Sets the field to zeros.

condata
The 8 bytes of connection data.

The connection data is passed to all of the connector exits and is for your use only; the TPF system does not use this information. A possible use for the connection data is as a pointer to a control block that represents the connector.

To code, specify the name or address of the 8-character input field that contains the connect data.

STRDISP
Specifies the disposition or persistence attribute of the CF list or cache structure when all connections are released.

The structure disposition determines whether the CF list or cache structure remains allocated or not when there are no connections to the CF list or cache structure.

Specify one of the following:

KEEP
Indicates that when there are no connections to the CF list or cache structure, it remains allocated. For example, if the data structure must be kept permanently on a CF, specify a structure disposition of KEEP. A CF list or cache structure that remains allocated when there are no connections is called a persistent structure.

DELETE
Indicates that the CF list or cache structure becomes unallocated when there are no connections to the CF list or cache structure.

CONNAME
Specifies a connection name that identifies your connection to the CF list or cache structure where:

GENERATED_NAME
Indicates a unique connection name to be generated by the TPF system.

conname
Indicates a unique name for each connection to a CF list or cache structure and meets the following requirements:
  • The name must begin with an uppercase alphabetic character.
  • The name must be 16 characters long and padded on the right with blanks if necessary.
  • The name can contain numeric characters, uppercase alphabetic characters, and underscores.

To code, specify the name or address of a 16-character field that contains the unique connection name to identify your connection to the CF list or cache structure.

CFLEVEL=cflevel
Specifies the CF level of the CF. The connector requires the CF list or cache structure to be allocated in at least this specified CF level. If you specified a CF level that is higher than that supported by the TPF system on which the requester runs, the connection is not successful.

The ICFCAATPFMAXCFLEV field of the CFCONC answer area contains the maximum CF level supported by the TPF system. The ICFCAACFLEVEL field contains the actual CF level of the CF in which the CF list or cache structure was allocated.

To change to a different CF level, you must disconnect from the CF list or cache structure and then connect to it again, specifying a different CF level. See CFDISC-Disconnect from a Coupling Facility List or Cache Structure for more information about disconnecting from a CF list or cache structure.

To code, specify the name or address of the fullword input field that contains the CF level required.

TYPE
Identifies the type of CF structure in the CF to which you want to connect.

Specify one of the following:

LIST
Indicates that the structure is a CF list structure.

CACHE
Indicates that the structure is a CF cache structure.

ANSAREA=ansarea
Specifies the address of the CFCONC answer area. When the CFCONC macro has been completed, it returns information to the caller in the CFCONC answer area. The requester can use the ICFCAA DSECT to map the CFCONC answer area. The CFCONC answer area must begin on a doubleword boundary and storage for this parameter must be in the same 4 K page.

To code, specify the name or address of the CFCONC answer area.

ANSLEN=anslen
Specifies the length of the CFCONC answer area. The length should be long enough to accommodate the ICFCAA DSECT mapping of the CFCONC answer area.

To code, specify the name or address of a fullword input field that contains the length of the CFCONC answer area.

Parameter for CF Cache Structures (TYPE=CACHE)

VECTORLEN=vectorlen
Specifies the number of cache buffers in the local storage of the requester that require concurrent registration. The requester uses the vector length to map each local cache buffer to a named data entry in the CF cache structure. The value you specify must be a multiple of 32 or the TPF system rounds up the value to a multiple of 32.

To code, specify the name or address of the fullword field that contains the number of cache buffers in the local storage of the requester.

Parameters for CF List Structures (TYPE=LIST)

ELEMCHAR=elemchar
Specifies the value of the element characteristic, which is used to determine the CF list structure element size. This size is calculated with the formula 256 × (2**ELEMCHAR), where ELEMCHAR is used as the power of 2. For example, if the value referenced by the ELEMCHAR parameter is 0, the size of each CF list structure element is 256 bytes.

Valid values for the ELEMCHAR parameter range from 0 to a maximum determined by the CF model limitation on the CF list structure element size.

Note:
The CF list structure element size determines the size of the data entry, which is the data written to and read from the CF list structure. A data entry can be up to 16 times the data element size as indicated by the element characteristic.

Specify either the ELEMCHAR or ELEMINCRNUM parameter to define the CF list structure element size. If neither parameter is specified, the CF list structure is allocated as if the value of the ELEMCHAR parameter was specified as 0.

To code, specify the name or address of the 1-byte field that contains the value of the element characteristic.

ELEMINCRNUM=elemincrnum
Specifies the element increment number that is used to determine the CF list structure element size. This size is calculated with the formula 256 × ELEMINCRNUM. For example, if the value referenced by the ELEMCHAR parameter is 1, the size of each CF list structure element is 256 bytes.

The valid values for ELEMINCRNUM range from 1 to a maximum determined by the CF model limitation on the size of the CF list structure element. The value you specify must be a power of 2.

Note:
The CF list structure element size determines the size of the data entry, which is the data written to and read from the CF list structure. A data entry can be up to 16 times the data element size as indicated by the element increment number.

Specify either the ELEMCHAR or the ELEMINCRNUM parameter to define the CF list structure element size. If neither parameter is specified, the CF list structure is allocated as if the value of the ELEMCHAR parameter was specified as 0.

To code, specify the name or address of the 1-byte field that contains the value of the element increment number.

MAXELEMNUM=maxelemnum
Specifies a value that determines the maximum number of data elements for each list entry in the CF list structure. The value you specify can be from 1 to 16 bytes. If you do not specify a value, a value of 16 is provided as the default. The maximum list entry size, in bytes, equals the value specified for the MAXELEMNUM parameter multiplied by the CF list structure element size obtained from the value you specified for either the ELEMCHAR or ELEMINCRNUM parameter. For example, if the value referenced by the ELEMCHAR parameter is 0 and the value referenced by the MAXELEMNUM parameter is 1, the maximum list entry size is 256 bytes. If the value referenced by the ELEMCHAR parameter is 4 and the value referenced by the MAXELEMNUM parameter is 16, the maximum list entry size is 65 536.

To ensure that the CF can assign all possible data elements allocated in a CF list structure to a list entry, the value specified for this parameter must be greater than or equal to the value specified for the ELEMENTRATIO parameter divided by the value specified for the ENTRYRATIO parameter. The MAXELEMNUM parameter is ignored if the value referenced by the ELEMENTRATIO parameter is 0.

If this parameter is not specified, the CF list structure is allocated as if the value of the MAXELEMNUM parameter was specified as 16.

To code, specify the name or address of the 2-byte field that contains a value that determines the maximum number of data elements for each list entry in the CF list structure.

ELEMENTRATIO=elementratio
Specifies a value to express the data element portion of the entry-to-element ratio of the CF list structure. If a value of 0 is specified for the ELEMENTRATIO parameter, the CF list structure is allocated without data elements. If this parameter is not specified, the CF list structure is allocated as if the value of the ELEMENTRATIO parameter was specified as 1.

To code, specify the name or address of the 2-byte field that contains a value to express the data element portion of the entry-to-element ratio of the CF list structure.

ENTRYRATIO=entryratio
Specifies a value to express the list entry portion of the entry-to-element ratio of the CF list structure.

To code, specify the name or address of the 2-byte field that contains a value to express the list entry portion of the entry-to-element ratio.

ADJUNCT
Specifies whether adjunct data areas are associated with each list entry in the CF list structure. Each adjunct data area can contain 64 bytes of user-defined data such as information about the status of the data entry or time stamp. You can specify one of the following:

NO
Indicates that there are no adjunct data areas specified for the CF list structure.

YES
Indicates that each list element in the CF list structure has an associated adjunct data area of 64 bytes.

LISTCNTLTYPE
Specifies whether the CF maintains and tracks list limits based on the number of list entries or the number of data elements for each list.

Specify one of the following:

ENTRY
Specifies that the list limits are identified and tracked as limits on the number of entries that may reside on the list. For example, if your main concern is to limit the number of entries that might build up on a list, limit the number of list entries for each list.

ELEMENT
Specifies that the list limits are identified and tracked as limits on the total number of data elements that may be associated with entries on the list. For example, if your main concern is to prevent the entries on a given list from consuming too much of the storage in a CF list structure, limit the number of data elements on a list.

REFOPTION
Specifies how to reference list entries in the CF list structure. Specify one of the following:

NOKEYNAME
Indicates that the list entry is located by the list entry identifier (LEID). The LEID is assigned for each list entry that is in use in the CF list structure. Keys or names are not used to reference list entries.

KEY
Indicates that the list entry is located by a key value. When creating the list entry, you can assign a key value to one or more list entries. Keyed entries allow users to maintain list entries in a keyed order. For example, if the list entries represent units of work ordered by priority, you could choose keyed entries.

NAME
Indicates that the list entry is located by a unique name. When creating the list entry, you can assign a unique name to each list entry. Named entries allow users to reference list entries by a user-defined name. If the list entries represent customer records in a particular order, you could choose named entries.

VECTORLEN=vectorlen
Specifies the number of list notification vector entries in the vector that this connection will be monitoring for list transitions. A list transition occurs when an empty list in the CF list structure becomes nonempty (changes from an empty state to a nonempty state). This value is rounded up to a multiple of 32.

To code, specify the name or address of the fullword field that contains the number of list notification vector entries in the vector.

LISTTRANEXIT=listtranexit
Identifies the address of the list transition exit routine for the requester. The list transition exit routine notifies you when one or more lists that you are monitoring changed from an empty state to a nonempty state.

To code, specify the name or address of the list transition exit for the requester.

LISTHEADERS=listheaders
Specifies the number of lists to be allocated in the CF list structure. This number must be greater than 0.

To code, specify the name or address of the fullword input field that contains the number of list headers you want allocated.

LOCKENTRIES=lockentries
Specifies the number of lock entries for the CF list structure. If this value is not a power of 2, it is rounded up to the nearest power of 2. If you do not specify a value or the requester specifies 0, the CF does not support serialization for the allocated CF list structure.

To code, specify the name or address of the fullword field that contains the number of lock entries for the CF list structure.

Entry Requirements

Return Conditions

When control returns to the caller of the CFCONC macro, the general-purpose registers (GPRs) contain the following:

Register
Contents

 15 
Return code in the high-order 2 bytes and a reason code in the low-order 2 bytes.

All other registers remain unchanged. Table 1 shows the hexadecimal return code, reason code, and equate symbol associated with each reason code. The ICFEQ DSECT provides equate symbols for the return and reason codes. The following are the equate symbols associated with each hexadecimal return code:

Return Code
Equate Symbol

 0000 
ICFRRCOK

 0004 
ICFRRCWARNING

 0008 
ICFRRCPARMERROR

 000C 
ICFRRCENVERROR

 0010 
ICFRRCCOMPONENT.

Table 1. Return and Reason Codes for the CFCONC Macro

Hexadecimal Return Code Hexadecimal Reason Code Equate Symbol Meaning and Action
0000 None Equate Symbol: None.

Meaning: The function is completed successfully and the TPF system returns data to the CFCONC answer area. Use the ICFCAA DSECT to map the CFCONC answer area.

Action: None. It is the responsibility of the user to verify that the structure attributes, as recorded in the CFCONC answer area, are acceptable.

0008 0801 Equate Symbol: ICFRRCBADPARMLIST

Meaning: A program error occurred because the address of the CFCONC parameter list is zero.

Action: Verify that the address is not corrupted.

0008 0804 Equate Symbol: ICFRRCBADVERSIONNUM

Meaning: A program error occurred because the version number found in the CFCONC parameter list is not valid.

Action: Do the following:

  1. Verify that your program did not overlay the parameter list storage.
  2. Verify that your program was assembled with the correct macro library for the release of the TPF system on which your program is running.
0008 080D Equate Symbol: ICFRRCAREATOOSMALL

Meaning: A program error occurred because the CFCONC answer area is too small as indicated by the length of the CFCONC answer area specified on the ANSLEN parameter.

Action: Do the following:

  1. Ensure that the value specified on the ANSLEN parameter correctly reflects the size of the CFCONC answer area. The size of the CFCONC answer area is specified on the ANSLEN parameter.
  2. Ensure that the length of the CFCONC answer area is large enough to contain the data returned.
0008 080E Equate Symbol: ICFRRCBADAREA

Meaning: A program error occurred because a pointer to the CFCONC answer area is null.

Action: Provide a valid pointer in your program.

0008 081B Equate Symbol: ICFRRCNOLENTRIES

Meaning: A program error occurred because the number of lock entries specified on the LOCKENTRIES parameter is 0.

Action: If the lock entries are in use, ensure that the value specified on the LOCKENTRIES parameter is greater than 0.

0008 081C Equate Symbol: ICFRRCNOLISTHDRS

Meaning: A program error occurred because the number of list headers specified on the LISTHEADERS parameter is 0.

Action: Ensure that the value specified on the LISTHEADERS parameter is greater than 0.

0008 081F Equate Symbol: ICFRRCCONNAME

Meaning: A program error occurred because the connection name specified for the CONNAME parameter matches the connection name of another active connection to the same CF structure. The connection name you specify must be unique for each connection to a CF structure.

Action: Ensure that the connection name specified for the CONNAME parameter is unique and not already connected to the CF structure or allow the TPF system to generate a unique connection name.

0008 0820 Equate Symbol: ICFRRCSTRTYPE

Meaning: A program error occurred because the CF structure type specified does not match the CF structure type allocated previously. When you connect to an allocated CF structure, you cannot change the structure type attribute. The request fails.

Action: Specify a value for the TYPE parameter that matches the CF structure type specified for the original CF structure.

0008 0821 Equate Symbol: ICFRRCSTRSERIAL

Meaning: A program error occurred because the serialization attribute for a CF list structure, which is specified on the LOCKENTRIES parameter, does not match the previously allocated CF list structure. When you connect to an allocated CF list structure, you cannot change the structure attributes.

Action: Specify a value on the LOCKENTRIES parameter that matches the value originally specified for the CF list structure.

0008 0823 Equate Symbol: ICFRRCCONNAMEERR

Meaning: A program error occurred because the connection name specified on the CONNAME parameter is not valid.

Action: Verify that the connection name specified is valid.

0008 0824 Equate Symbol: ICFRRCCFNAMEERR

Meaning: A program error occurred because the CF name specified on the CFNAME parameter is not valid.

Action: Verify that the CF name specified is valid.

0008 0825 Equate Symbol: ICFRRCSTRNAMEERR

Meaning: A program error occurred because the structure name specified on the STRNAME parameter is not valid.

Action: Verify that the structure name specified is valid.

0008 085A Equate Symbol: ICFRRCINVALIDCACHEPARM

Meaning: A parameter that is only valid for a CF list structure was specified for a CF cache structure. See Parameter for CF Cache Structures (TYPE=CACHE) for information about valid CF cache parameters.

Action: Verify that the parameters specified are valid for a CF cache structure.

0008 085F Equate Symbol: ICFRRCINVALIDVECTORLEN

Meaning: A program error occurred because the value specified for the VECTORLEN parameter for a CF cache structure was equal to zero. The request fails.

Action: Specify a nonzero value for the VECTORLEN parameter for a CF cache structure.

0008 0861 Equate Symbol: ICFRRCENTRYRATIO

Meaning: A program error occurred because the values specified on the ELEMENTRATIO and ENTRYRATIO parameters are not valid. When the value specified for the ELEMENTRATIO parameter is greater than 0, the value specified for the ENTRYRATIO parameter must also be greater than 0.

Action: Ensure you specify a value that is greater than 0 for the ENTRYRATIO parameter.

0008 0862 Equate Symbol: ICFRRCMAXELEMNUM

Meaning: A program error occurred because the values specified for the ELEMENTRATIO and MAXELEMNUM parameters are not valid. When allocating a CF list structure, if the value specified for the ELEMENTRATIO parameter is not 0, the value specified for the MAXELEMNUM parameter must be greater than or equal to that value, divided by the value specified for the ENTRYRATIO parameter.

Action: Ensure you modify the value specified for the MAXELEMNUM parameter so that it meets these requirements.

0008 0864 Equate Symbol: ICFRRCELEMINCRNUMELEMCHAR

Meaning: A program error occurred because both the ELEMCHAR and ELEMINCRNUM parameters were specified. Only one of these parameters can be specified.

Action: Issue the CFCONC macro again, specifying either the ELEMCHAR or ELEMINCRNUM parameters.

0008 086B Equate Symbol: ICFRRCELEMINCRNUM

Meaning: A program error occurred because the value specified on the ELEMINCRNUM parameter is not valid.

Action: Ensure you specify a value greater than 0 and a power of 2.

0008 0871 Equate Symbol: ICFRRCMAXELEMNUMELEMCHAR

Meaning: A program error occurred because the values specified on the MAXELEMNUM parameter and either the ELEMCHAR or ELEMINCRNUM parameter will result in a list entry having a maximum data entry size greater than the 64-KB limit.

Action: Ensure you change the values specified on the MAXELEMNUM and ELEMCHAR parameters, as appropriate, to meet the 64-KB limit.

0008 0881 Equate Symbol: ICFRRCBADCFLEVEL

Meaning: A program error occurred because you tried to use a function that is not supported by the CF level specified on the CFLEVEL parameter. The connector requires that the CF list structure be allocated in at least this specified CF level. If you specify a CF level that is higher than that supported by the TPF system on which the requester runs, the connection is not successful.

Action: Issue the CFCONC macro again specifying, a value for the CFLEVEL parameter that supports the functions you want to use.

0008 08F2 Equate Symbol: ICFRRCRESTARTINCOMPLETE

Meaning: A program error occurred because the TPF system has not yet completed CF restart.

Action: Ensure that you wait until CF restart is completed.

0008 08F3 Equate Symbol: ICFRRCCONAUTHERR

Meaning: An attempt was made to connect to a CF locking structure, but another processor is connected to the structure with the processor ID of this processor.

Action: Do the following:

  1. Ensure that no other processor performs an initial program load (IPL) with the processor ID of this processor.
  2. Enter ZPSMS PR FORCE DEACT processor ID to ensure that any processor that was previously IPLed with the processor ID of this processor has been deactivated.
000C 0C02 Equate Symbol: ICFRRCNOMORECONNS

Meaning: This is an environmental error that occurred because the CF structure already has the maximum number of allowed connections.

Action: Try your request again at a later time.

000C 0C03 Equate Symbol: ICFRRCNOMORESTRUCTS

Meaning: This is an environmental error that occurred because the CF cannot allocate a spare CF structure identifier (ID).

Action: Try your request again at a later time.

000C 0C06 Equate Symbol: ICFRRCNOCONN

Meaning: This is an environmental error that occurred because the TPF system has not established a connection to the CF that contains the specified CF list structure. Issuing CF commands such as VARY PATH OFFLINE or CONFIG CHP OFFLINE and hardware errors such as CF failures or path failures, may prevent this connection from being established.

Action: Determine why the connectivity was not established and try your request again.

000C 0C11 Equate Symbol: ICFRRCDEFINE

Meaning: This is an environmental error that occurred because the local list notification vector could not be defined.

Action: Try your request again at a later time.

000C 0C24 Equate Symbol: ICFRRCINVSTRSIZE

Meaning: This is an environmental error that occurred because the size specified for the CF structure was not valid.

Action: Do the following:

  1. Specify a valid value for the size of the CF structure.
  2. Try your request again, specifying a valid CF structure size for the STRSIZE parameter.
000C 0C25 Equate Symbol: ICFRRCSTRFAILURE

Meaning: This is an environmental error that occurred because of a CF structure failure.

Action: See your system programmer for more information.

000C 0C26 Equate Symbol: ICFRRCREALLOCERROR

Meaning: This is an environmental error that occurred because a second allocation to change the CF structure name to the requested name was not successful.

Action: See your system programmer for more information.

000C 0C53 Equate Symbol: ICFRRCCFLEVEL

Meaning: The CF level you specified is greater than the current CF level supported.

Action: See your system administrator for more information.

000C 0CF0 Equate Symbol: ICFRRCAUTHLOCKERROR

Meaning: The connect request was rejected because the CF lock was not obtained because of an error that occurred. This error occurs when the CF fails to respond to CF commands.

Action: None.

000C 0CF2 Equate Symbol: ICFRRCSYNCERROR

Meaning: Your request to connect to a CF list structure on the CF was not successful because the time stamp in the structure user controls did not match the time stamp found in the coupling facility structure block (CFSB). The CFSB is deleted.

Action: Try to connect to the CF list structure again.

000C 0CF3 Equate Symbol: ICFRRCCFNOTADDED

Meaning: A program error occurred because the specified CF was not added to the processor configuration.

Action: Do the following:

  1. Enter the ZMCFT ADD command to add the specified CF to the processor configuration.
  2. Issue your request again.

See TPF Operations for more information about the ZMCFT ADD command.

000C 0CF4 Equate Symbol: ICFRRCCFNOTACTIVE

Meaning: A program error occurred because the specified CF was not added to the processor configuration.

Action: Do the following:

  1. Enter the ZMCFT ADD command to add the specified CF to the processor configuration.
  2. Issue your request again.

See TPF Operations for more information about the ZMCFT ADD command.

000C 0CF5 Equate Symbol: ICFRRCCFSBFILEERROR

Meaning: The connect request was not successful because the TPF system could not create the coupling facility structure block (CFSB) or update it on file. This error may be accompanied by additional error messages that provide more information about the error.

Action: Determine the cause of the error and try your connect request again.

0010 1000 Equate Symbol: ICFRRCCOMPERROR

Meaning: A component error occurred because a CF command was not successful.

Action: See your system programmer for more information.

Programming Considerations

Examples

None.