gtps1m1p | System Macros |
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
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.
To code, specify the name or address of the 16-character input field that contains the CF list or cache structure name.
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.
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.
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:
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.
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.
Specify one of the following:
To code, specify the name or address 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)
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)
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.
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.
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.
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.
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.
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.
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.
Specify one of the following:
To code, specify the name or address of the fullword field that contains the number of list notification vector entries in the vector.
To code, specify the name or address of the list transition exit for the requester.
To code, specify the name or address of the fullword input field that contains the number of list headers you want allocated.
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:
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:
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:
|
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:
|
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:
|
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:
|
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:
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:
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