gtpd1m30 | Database Reference |
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.
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:
- You can receive data in the CFCONC answer area, which is mapped by the
ICFCAA DSECT.
- You are connected to the CF structure you requested.
- You can request structure services that are valid for a CF
structure.
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.
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:
- All five return codes are returned in the high-order 2 bytes of register
15 (R15).
- If the return code is not zero, the low-order 2 bytes of R15 contain
reason codes. See TPF System Macros for an
explanation of these reason codes.
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.
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.
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.
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:
- All connections to a specific CF structure are in use.
- The requesting TPF system does not have connectivity to the CF that
contains the specified CF structure.
- The CF function is not active; for example, CF restart did not end
successfully or the TPF system has not allocated the fixed file
records.