gtpc2m7t | C/C++ Language Support User's Guide |
This function allocates a coupling facility (CF) list or cache structure
and connects to it, or connects 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.
Format
#include <c$fapi.h>
int tpf_cfconc(struct icfco *parms);
- parms
- A pointer to the tpf_cfconc parameter list.
Normal Return
- ICF_SUCCESS
- The function is completed successfully and the TPF system returns data in
a tpf_cfconc answer area, which is a structure of type
ICFCAA. The c$cfaa.h header file contains
ICFCAA.
Error Return
One of the following:
- ICFRRCBADPARMLIST
- A program error occurred because a pointer to the tpf_cfconc
parameter list is null.
Correct your program so the value is not null.
- ICFRRCAREATOOSMALL
- A program error occurred because the tpf_cfconc answer area is
too small as indicated by the length specified in the ANSLEN field of the
tpf_cfconc parameter list.
Correct your program and ensure that the length specified in the ANSLEN
field accurately reflects the size of the tpf_cfconc answer
area. In addition, ensure that the length of the tpf_cfconc
answer area is large enough to contain the data returned.
- ICFRRCBADAREA
- A program error occurred because the pointer to the tpf_cfconc
answer area is null.
Correct your program so the value is not null.
- ICFRRCNOLISTHDRS
- A program error occurred because the number of list headers specified in
the LISTHEADERS field of the tpf_cfconc parameter list is
zero.
Correct your program to use a value greater than zero.
- ICFRRCCONNAME
- A program error occurred because the connection name specified in the
tpf_cfconc parameter list matches the connection name of another
active connection to the same CF structure. The connection name is used
to identify your connection to a CF structure; therefore, the connection
name must be unique for each connection to a CF structure.
Correct your program to use a connection name that is not already connected
to the CF structure or allow the TPF system to generate a unique name for
you.
- ICFRRCSTRTYPE
- A program error occurred because the CF structure type specified in the
tpf_cfconc parameter list does not match the type of the CF
structure allocated previously. When you connect to an allocated CF
structure, you cannot change the structure type attribute. The request
fails.
Correct your program to use a CF structure type that matches the type
specified for the original CF structure.
- ICFRRCCONNAMEERR
- A program error occurred because the connection name specified in the
tpf_cfconc parameter list is not valid.
Correct your program so that the connection name 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 (_).
- ICFRRCCFNAMEERR
- A program error occurred because the CF name specified in the
tpf_cfconc parameter list is not valid.
Correct your program so that the CF name meets the following requirements
and then try the request again:
- The name must be a 5- to 8-character alphanumeric name.
- The first character must be an alphabetic character.
- ICFRRCSTRNAMEERR
- A program error occurred because the structure name specified in the
tpf_cfconc parameter list is not valid.
Correct your program so that the structure name meets the following
requirements:
- The name must begin with an uppercase alphabetic character.
TPF-defined structure names begin with I or TPF.
- The name must be 16 characters long, padded on the right with blanks if
necessary.
- The name can contain numeric characters and uppercase alphabetic
characters, and underscores (_).
- ICFRRCINVALIDCACHEPARM
- A program error occurred because a value that is only valid for a CF list
structure was specified for the CF cache structure.
Verify that the values specified are valid for a CF cache structure.
- ICFRRCINVALIDVECTORLEN
- A program error occurred because the vector length specified in the
tpf_cfconc parameter list for a CF cache structure was equal to
zero. The request fails.
Correct your program by specifying a value of nonzero for the vector length
for a CF cache structure.
- ICFRRCENTRYRATIO
- A program error occurred because the values specified in the ELEMENTRATIO
and ENTRYRATIO fields of the tpf_cfconc parameter list are not
valid. When the value specified in the ELEMENTRATIO field is greater
than zero, the value specified in the ENTRYRATIO field must also be greater
than zero.
Correct your program so that the value specified in the ENTRYRATIO field is
greater than zero.
- ICFRRCMAXELEMNUM
- A program error occurred because the values specified in the ELEMENTRATIO
and MAXELEMNUM fields of the tpf_cfconc parameter list are not
valid. When allocating a CF list structure, if the value specified in
the ELEMENTRATIO field is not zero, the value specified in the MAXELEMNUM
field must be greater than or equal to the ELEMENTRATIO value divided by the
value you specified in the ENTRYRATIO field.
Correct your program so that the value specified for the MAXELEMNUM field
meets these requirements.
- ICFRRCELEMINCRNUMELEMCHAR
- A program error occurred because nonzero values were specified for both
the ICFCOELEMCHAR and ICFCOELEMINCRNUM fields of the tpf_cfconc
parameter list.
Correct your program to pass only one of these parameters and try the
request again.
- ICFRRCELEMINCRNUM
- A program error occurred because the value specified in the ELEMINCRNUM
field of the tpf_cfconc parameter list is not valid.
Correct your program to specify a value greater than zero and a power of
2.
- ICFRRCMAXELEMNUMELEMCHAR
- A program error occurred because the values specified in the MAXELEMNUM
field and either the ELEMCHAR or ELEMINCRNUM fields of the
tpf_cfconc parameter list will result in a list entry having a
maximum data entry size greater than the 64-KB limit..
Correct your program to change the values of the MAXELEMNUM and ELEMCHAR
fields, as appropriate, to meet the 64-KB limit.
- ICFRRCCONAUTHERR
- An attempt was made to connect to a TPF locking structure, but another
processor has already connected to the structure with the processor ID of this
processor.
Do the following:
- Ensure the correct processor ID was specified for this processor during an
initial program load (IPL).
- Enter ZPSMS PR FORCE DEACT processor ID to ensure
that any processor that was IPLed previously with the processor ID of this
processor has been deactivated.
- ICFRRCNOMORECONNS
- An environmental error occurred because the CF structure already has the
maximum number of allowed connections.
Try your request again at a later time.
- ICFRRCNOMORESTRUCTS
- An environmental error occurred because the CF cannot allocate a spare CF
structure identifier (ID).
Try your request again at a later time.
- ICFRRCINVSTRSIZE
- An environmental error occurred because the size specified for the CF
structure was not valid.
Correct your program and try the request again.
- ICFRRCSTRFAILURE
- An environmental error occurred because of a CF structure failure.
- ICFRRCREALLOCERROR
- An environmental error occurred because the second allocation to change
the CF structure name from TPFALLOC to the requested name was not
successful.
Disconnect from the CF structure.
- ICFRRCCFLEVEL
- An environmental error occurred because the requester specified a CF level
that is greater than the level of the CF.
- ICFRRCAUTHLOCKERROR
- The connect request was rejected because an error prevented the CF lock
from being obtained. This error occurs when the CF fails to respond to
CF commands or the CF is damaged.
- ICFRRCCFNOTADDED
- A program error occurred because the CF was not added to the processor
configuration.
Do the following:
- Enter the ZMCFT ADD command to add the specified CF to the processor
configuration.
- Issue your request again.
See TPF Operations for more information about the
ZMCFT ADD command.
- ICFRRCCFSBFILEERROR
- 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.
Correct the error and try to connect to the CF list structure again.
- ICFRRCCOMPERROR
- A component error occurred because of a TPF system processing
failure.
Try the request again at a later time.
Programming Considerations
- If the specified CF list or cache structure is not allocated when the
tpf_cfconc function is called, the CF list or cache structure is
allocated and the connection is established.
- If the specified CF list or cache structure is already allocated when the
tpf_cfconc function is called, the TPF system connects to the
existing CF structure.
- The CF structure may not be allocated with all the requested
attributes. All connectors, whether the first or subsequent, are
informed of the structure attributes through the tpf_cfconc answer
area. The connector must ensure the structure attributes are
acceptable. If the structure attributes are not acceptable, you can
disconnect from the CF structure.
- Applications should use the newCache function with the
processor shared (Cache_ProcS) parameter specified to create a CF cache
structure rather than using the tpf_cfconc function.
Examples
The following example shows a connection to a CF list structure on a
CF. In this example:
- The CF name is in the cf_name variable.
- icfostrdisp is set to ICFCOKEEP, which means the structure
disposition is KEEP.
- icfcotype is set to ICFCOLIST, which means this structure uses
a CF list structure.
- Setting icfcostrctl means:
- The list limits are tracked by ENTRY.
- The list entries have an adjunct area.
- Entries in the list will be located by name and not by key.
- The CF list structure name is in the structure_name
variable.
- The number of lists in this CF list structure is set by setting
icfcolistheaders to list_headers.
- Setting icfcovectorlen to 32 means lists will be monitored in
the CF so a vector will be allocated.
#include <c$cfco.h>
#include <c$fapi.h>
struct icfco* parm_ptr = NULL;
struct icfcaa* answer_ptr = NULL;
/*****************************************************/
/* Get storage for the connect parameter area and */
/* the connect answer area. Initialize the pointers */
/*****************************************************/
crusa( 2, D4, D5 );
parm_ptr = getcc( D4, GETCC_TYPE+GETCC_FILL, L1, 0x00 );
answer_ptr = getcc( D5, GETCC_TYPE+GETCC_FILL, L1, 0x00 );
/*****************************************************/
/* Now perform the setup and call of tpf_cfconc() */
/*****************************************************/
parm_ptr->icfcoansarea = answer_ptr;
parm_ptr->icfcoanslen = _SBSZE;
parm_ptr->icfcocflevel = CFL_CFLEVEL;
memcpy( &parm_ptr->icfcocfname,
cf_name,
sizeof( parm_ptr->icfcocfname ) );
parm_ptr->icfcocompleteexit = complete_exit;
memcpy( &parm_ptr->icfcoconname,
"GENERATED_NAME",
sizeof( parm_ptr->icfcoconname ) );
parm_ptr->icfcostrdisp = ICFCOKEEP;
parm_ptr->icfcotype = ICFCOLIST;
parm_ptr->icfcostrctl = (unsigned char)(ICFCOENTRY+
ICFCOADJUNCT+ICFCONAMESUP+ICFCONOKEYSUP);
memcpy( &parm_ptr->icfcostrname,
structure_name,
sizeof( parm_ptr->icfcostrname ) );
parm_ptr->icfcostrsize = structure_size;
parm_ptr->icfcoelemchar = 0;
parm_ptr->icfcoelemincrnum = 1;
parm_ptr->icfcoelementratio = 1;
parm_ptr->icfcoentryratio = 1;
parm_ptr->icfcolistheaders = list_headers;
parm_ptr->icfcolisttranexit = list_transition_exit;
parm_ptr->icfcolockentries = 0;
parm_ptr->icfcomaxelemnum = 1;
parm_ptr->icfcovectorlen = 32;
if( (rc = tpf_cfconc( parm_ptr ) != 0 )
{
/* Handle the error or warning */
} /* End of error while connecting */
Related Information