gtpc2m7tC/C++ Language Support User's Guide

tpf_cfconc-Connect to a Coupling Facility List or Cache Structure

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:

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:

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:

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:

  1. Ensure the correct processor ID was specified for this processor during an initial program load (IPL).
  2. 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:

  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.

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

Examples

The following example shows a connection to a CF list structure on a CF. In this example:

#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