gtps1m1tSystem Macros

CFVCTC-Check or Modify a List Notification Vector

Use this system macro to perform the following operations on your list notification vector:

Format




VECTORTOKEN=vectortoken
Identifies the list notification vector on which you want the specified request (using the REQUEST parameter) performed. This list notification vector was initially created by the CFCONC macro, if the VECTORLEN parameter was coded, and the vector token was returned in the ICFCAAVECTOK field of the CFCONC answer area. See CFCONC-Connect to a Coupling Facility List or Cache Structure for more information about the CFCONC macro.

To code, specify the name or address of an 8-byte field that contains the token for the list notification vector.

WORKAREA=workarea
Specifies a work area that is used by the CFVCTC macro. The minimum required length for the work area is defined by the ICFVWALEN equate. This equate is defined by the IFAPI data macro.

To code, specify the name or address of a work area that begins on a word boundary.

REQUEST
Allows you to manage the list notification vector, vector entries, and a list.

Specify one of the following:

MODIFYVECTORSIZE
Modifies the size of your list notification vector.

LTVECENTRIES
Loads and tests a range of vector entries associated with a list notification vector for a CF list structure.

TESTLISTSTATE
Tests whether a list you are monitoring is empty or not empty.

VECTORLEN=vectorlen
Specifies a fullword field that contains the new total number of vector entries in the list notification vector. The new number of vector entries can be greater than or less than the current number of vector entries, but must be greater than 0. If you specify a number that is not a multiple of 32, the TPF system will round up the number to a multiple of 32.

The TPF system tries to expand or contract your list notification vector to the size you specify.

To code, specify the name or address of the fullword field that contains the requested list notification vector length.

ACTUALVECTORLEN=actualveclen
Specifies a fullword field to receive the count of the new number of vector entries for the list notification vector after the REQUEST=MODIFYVECTORSIZE parameter is processed. The fullword field is valid only when control is passed to the routine specified by the LESSTHAN parameter.

To code, specify the name or address of the fullword field to contain the new list notification vector length if it differs from the requested list notification vector length.

MODIFYDONE=modifydone
Specifies the label to branch to if the CFVCTC macro is able to modify the list notification vector.

To code, specify the name or address of the label.

LESSTHAN=lessthan
Specifies the label to branch to if the CFVCTC macro cannot obtain enough storage to enlarge your list notification vector to the size you requested.

To code, specify the name or address of the label.

NOSTORAGE=nostorage
Specifies the label to branch to if the CFVCTC macro cannot obtain any storage to enlarge your list notification vector to the size you requested. The list notification vector size remains the same.

To code, specify the name or address of the label.

INVALIDTOKEN=invalidtokn
Specifies the label to branch to if the vector token you specified on the VECTORTOKEN parameter is not valid.

To code, specify the name or address of the label.

INVALIDLEN=invalidlen
Specifies the label to branch to if the value you specified on the VECTORLEN parameter is not valid.

To code, specify the name or address of the label.

VECTORINDEX=vectorindex
If REQUEST=LTVECENTRIES is coded, specifies the starting index of the range of vector entries that you want loaded and tested. The index you specify must be evenly divisible by 32. Thirty-two consecutive vector entries will be loaded and tested. The vector indexes for a specific vector of size N range from 0 to N-1.

If REQUEST=TESTLISTSTATE is coded, this parameter specifies a fullword field that contains the vector index entry associated with the list of interest. For a vector with N entries, valid vector index values range from 0 to N-1.

To code, specify the name or address of the label.

BITSTRING=bitstring
This is a required output field that contains vector entry state information for the range of vector entries specified. This field contains 32 bits. The first bit represents the first vector entry specified on the VECTORINDEX parameter and continues up to a maximum of 32 vector index entries. The bits are interpreted as follows:

0
The vector entry that corresponds to this bit position indicates that the monitored list is not empty

1
The vector entry that corresponds to this bit position indicates that the monitored list is empty.

To code, specify the name or address of a fullword field.

ALLEMPTY=allempty
Specifies the label to branch to if all associated lists in the range of the vector entries are empty.

To code, specify the name or address of the label.

SOMENONEMPTY=somenonempty
Specifies the label to branch to if some of the associated lists in the range of vector entries are not empty.

To code, specify the name or address of the label.

INVALIDINDEX=invalidindex
Specifies the lable to branch to if the CFVCTC macro detects that the index value you specified is not valid.

To code, specify the name or address of the label.

LISTEMPTY=lstempty
Specifies the label to branch to if the CFVCTC macro finds the list of interest empty.

To code, specify the name or address of the label.

LISTNONEMPTY=lstnonempty
Specifies the label to branch to if the CFVCTC macro finds the list of interest not empty.

To code, specify the name or address of the label.

Entry Requirements

None.

Return Conditions

When the CFVCTC macro returns control to your program, register 15 (R15) is undefined and all remaining registers are unchanged.

The following tables contain the reasons for which each branch routine may be called and the suggested recovery actions.

Table 3. Branch Routines for the CFVCTC Macro with REQUEST=MODIFYVECTORSIZE Coded

Routine Meaning and Action
MODIFYDONE Meaning: The list notification vector was modified as requested.

Action: None.

LESSTHAN Meaning: This is a system error. The list notification vector is smaller than the size you requested because there was not enough storage available. The new number of vector entries is returned in the field specified by the ACTUALVECTORLEN parameter.

Action: Do the following:

  1. If you need a larger list notification vector, try the request later when more storage is available.
  2. If the problem continues, see your system programmer to determine the cause of the problem and to correct it.
NOSTORAGE Meaning: This is a system error. Storage could not be obtained to increase the list notification vector size. The size remains unchanged.

Action: Do the following:

  1. If you need a larger list notification vector, try the request later when more storage is available.
  2. If the problem continues, see your system programmer to determine the cause of the problem and to correct it.
INVALIDTOKEN Meaning: This is a program error because the vector token you specified on the VECTORTOKEN parameter is not valid.

Action: Do the following:

  1. Check your program for errors such as the following:
    • You specified the address of the vector token incorrectly.
    • The vector token was overlaid or corrupted between the time you received it and the time you specified it.
    • You disconnected from the CF list structure using the CFDISC macro before issuing the CFVCTC macro. You must be connected to the CF list structure to issue the CFVCTC macro. See CFDISC-Disconnect from a Coupling Facility List or Cache Structure for more information about the CFDISC macro.
  2. Correct the error.
  3. Run the program again.
INVALIDLEN Meaning: This is a program error because the list notification vector length you specified on the VECTORLEN parameter is not valid. The list notification vector length must be greater than or equal to 1.

Action: Do the following:

  1. Correct the error by ensuring the list notification vector length specified is greater than 0.
  2. Run your program again.

Table 4. Branch Routines for the CFVCTC Macro with REQUEST=LTVECENTRIES Coded

Routine Meaning and Action
ALLEMPTY Meaning: All associated lists in the range of vector entries are empty.

Action: None.

SOMENONEMPTY Meaning: A list in the range of vector entries is not empty.

Action: None.

INVALIDINDEX Meaning: This is a program error because the vector index you specified on the VECTORINDEX parameter is not valid.

Action: Do the following:

  1. Check your program for errors such as the following:
    • You specified a vector index value that is not a multiple of 32.
    • You specified a vector index value greater than or equal to the number of vector entries. Vector index values for a vector with N entries range from zero to N-1.
    • You specified the address of the vector index value incorrectly.
  2. Correct the error.
  3. Run the program again.
INVALIDTOKEN Meaning: This is a program error because the vector token you specified on the VECTORTOKEN parameter is not valid.

Action: Do the following:

  1. Check your program for errors such as the following:
    • You specified the address of the vector token incorrectly.
    • The vector token was overlaid or corrupted between the time you received it and the time you specified it.
    • You disconnected from the CF list structure using the CFDISC macro before issuing the CFVCTC macro. You must be connected to the CF list structure to issue the CFVCTC macro. See CFDISC-Disconnect from a Coupling Facility List or Cache Structure for more information about the CFDISC macro.
  2. Correct the error.
  3. Run the program again.

Table 5. Branch Routines for the CFVCTC Macro with REQUEST=TESTLISTSTATE Coded

Routine Meaning and Action
LISTEMPTY Meaning: This list is empty.

Action: None.

LISTNONEMPTY Meaning: The list is not empty.

Action: None.

INVALIDINDEX Meaning: This is a program error because the vector index you specified on the VECTORINDEX parameter is not valid.

Action: Do the following:

  1. Check your program for errors such as the following:
    • You specified a vector index value greater than or equal to the number of vector entries. Vector index values for a vector with N entries range from zero to N-1.
    • You specified the address of the vector index value incorrectly.
    • Another unit of work modified the vector size while the REQUEST=TESTLISTSTATE parameter was being processed.
  2. Correct the error.
  3. Run the program again.
INVALIDTOKEN Meaning: This is a program error because the vector token you specified on the VECTORTOKEN parameter is not valid.

Action: Do the following:

  1. Check your program for errors such as the following:
    • You specified the address of the vector token incorrectly.
    • The vector token was overlaid or corrupted between the time you received it and the time you specified it.
    • You disconnected from the CF list structure using the CFDISC macro before issuing the CFVCTC macro. You must be connected to the CF list structure to issue the CFVCTC macro. See CFDISC-Disconnect from a Coupling Facility List or Cache Structure for more information about the CFDISC macro.
  2. Correct the error.
  3. Run the program again.

Programming Considerations

Examples

None.