ASSOCIATE EXIT

Notes:

¹ You can specify the operands in any order, as long as EPNAME is the last operand specified.

Authorization

Privilege Class: A

Purpose

Use ASSOCIATE EXIT to assign one or more entry points or external symbols to an exit point.

You can also assign entry points and external symbols to an exit point during initialization using the ASSOCIATE EXIT configuration file statement. For more information, see ASSOCIATE EXIT Statement in z/VM: CP Planning and Administration.

Operands

exit: is the number of the exit point to which you want to assign an entry point or external symbol. The variable exit must be a hexadecimal number between X'0000' and X'FFFF'.
REPlace: tells CP to replace the current list of entry point names and external symbols that are already associated with this exit point with the list specified after the EPNAME operand.
Note: The order that you specify the entry points and external symbols is the order in which CP will call them.
Following: tells CP to add the specified entry point names or external symbols to the end of the list of existing entry point names and external symbols that are already associated with the specified exit point number.
Note: The order that you specify the entry points and external symbols is the order in which CP will call them.
Preceding: tells CP to add the specified entry point names or external symbols to the beginning of the list of existing entry point names and external symbols that are already associated with the specified exit point number.
Note: The order that you specify the entry points and external symbols is the order in which CP will call them.
DISAble: tells CP not to call the entry points and external symbols associated with this exit point until you enable it. (For more information about enabling exit points, see Usage Note 4.) If omitted, DISABLE is the default.
ENable: tells CP to immediately start calling the entry points and external symbols associated with this exit point.
EPName name: is the name (or names) of the entry point or external symbol that CP calls when encountering this exit point number. Each name must be a 1- to 8-character string. The first character must be alphabetic or one of the following special characters: dollar sign ($), number sign (#), underscore (_), or at sign (@). The rest of the string can be alphanumeric characters, the 4 special characters ($, #, _, and @), or any combination thereof.
Note: The order that you specify the entry points and external symbols is the order in which CP will call them.

Usage Notes

Before you use the ASSOCIATE EXIT command, you should issue the CPXLOAD command or configuration file statement to load the customer-written CP routines for the exit point into the system execution space. These CP routines should contain the entry point names and external symbols that you will specify on the ASSOCIATE EXIT command.
If you do not issue the CPXLOAD command or statement first or you issue the ASSOCIATE EXIT command with an unknown entry point or external symbol, CP just ignores any entry point name or external symbol that it does not recognize and continues normal processing. If the unknown entry point or external symbol is part of a list associated with an exit point, CP continues processing the other members of the list. CP does not ignore an exit point because it cannot find one entry point or external symbol in the list. CP only ignores an exit point if it cannot find all the entry points and external symbols in the list.

For more information about the CPXLOAD command, see CPXLOAD.

For more information about the CPXLOAD Statement, see z/VM: CP Planning and Administration.
To display whether there are any unknown entry points or external symbols associated with an exit point, use the QUERY UNRESOLVED command (see QUERY UNRESOLVED).
If you issue the ASSOCIATE EXIT command and do not specify the ENABLE operand, CP will redefine the exit point with the information from your ASSOCIATE EXIT command, but will not call any of the entry points or external symbols associated with that exit point until you later enable it.
There are 2 ways to enable an exit point:
- Enter another ASSOCIATE EXIT command and specify the ENABLE operand, or
- Use the ENABLE EXITS command (see ENABLE EXITS).
By default, exit points are disabled. Thus, in general, you should follow any ASSOCIATE EXIT commands or statements with ENABLE EXITS commands or statements.
CP calls the entry points and external symbols for an exit point in the order that you specify them on the ASSOCIATE EXIT command, unless an entry point overrides this action. Any entry point can tell CP to change the normal processing flow by skipping one or all subsequent entry points or external symbols.
To display status and usage statistics information about a specific exit point, use the QUERY EXITS command (see QUERY EXITS).
Note: While processing the ASSOCIATE EXIT command (or statement), CP creates a CP exit block for the specified exit point. For a static exit point, CP does not create CP exit control blocks until you associate one or more entry points or external symbols with that exit point. If you try to issue a QUERY EXITS command against such an exit point, CP issues message HCP2752E as the response to your QUERY EXITS command. For a dynamic exit point, QUERY EXITS responds with the definition of the exit, even if there are no entry points associated with it.
To display the address of the CP exit block for a specific exit point, use the LOCATE XITBK command (see LOCATE XITBK). Again, if you have not associated one or more entry points or external symbols with the specified exit point, there is no CP exit block for CP to locate and display. Instead, CP issues error message HCP2752E.
To display the address of the CP indirect call locator block for a specific exit point, use the LOCATE ICLBK command (see LOCATE ICLBK).
To change the definition of an existing dynamic exit point, or to remove the exit point from the system, use the MODIFY EXIT command (see MODIFY EXIT).
To stop CP from calling the entry points and external symbols associated with one or more exit points after defining those exit points, use the DISABLE EXITS command (see DISABLE EXITS).
To remove the customer-written CP routines from the system execution space:
1. Use the DISASSOCIATE command (see DISASSOCIATE) to revoke all entry point and external symbol assignments made with the ASSOCIATE EXIT command or configuration file statement.
2. Use the CPXUNLOAD command (see CPXUNLOAD) to unload the customer-written CP routines.
Using the ASSOCIATE EXITS command or configuration file statement, you can add to the list of entry points and external symbols for an exit point, or you can replace the list. For example, if you associate entry points ZZZA1 and ZZZA2 with an exit point:
```
associate exit 1 epname zzza1 zzza2
Ready;
```
and then you associate additional entry points YYYB1 and YYYC2:
```
associate exit 1 preceding epname yyyb1 yyyc2
Ready;
```
the final list of entry points would be:
```
   YYYB1  YYYC2  ZZZA1  ZZZA2
```
To remove one or more entry points or external symbols from the list associated with an exit point, issue the ASSOCIATE EXIT command with the REPLACE operand and specify only those entry points and external symbols that you want CP to call.
If the exit point is disabled when you issue the ASSOCIATE EXIT command, CP immediately updates the list of entry points and external symbols with your changes. If the exit point is enabled, CP checks to see if the specified exit point is currently processing an exit request. If the exit point is not processing any requests, CP immediately updates the list with your changes. If the exit point is processing a request, CP waits until the current request is completed and then updates the list with your changes before processing any new exit requests.
After creating a CP exit block, CP will not erase that CP exit block until another IPL. Disabling the exit point affects certain fields in the CP exit block, but does not erase it. Disassociating the entry point names and external symbols erases those fields in the CP exit block, but does not erase the CP exit block itself.
For more information about user-defined exit points, see IBM-Defined CP Exit Points in z/VM: CP Exit Customization.

Responses

Response 1:

To associate entry point HCPSRC00 with exit number F and to replace any existing entry point associations, enter the following:

associate exit f epname hcpsrc00
Ready;

Response 2:

To add entry point HCPSRC04 at the end of the current list for exit point 9C, enter the following:

associate exit 9c following epname hcpsrc04
Ready;

Response 3:

Using the QUERY EXITS command and the ASSOCIATE EXIT command, you can see how you are changing the list of entry points:

query exit 5
Exit  Status        Calls    Returns Seconds
0005  Enabled           1          1 0.000122
      EPNAME     Attempts      Calls Seconds
      HCPSRC00          1          1 0.000116
Ready;

associate exit 5 following epname hcpsrc04
Ready;

query exit 5
Exit  Status        Calls    Returns Seconds
0005  Enabled           1          1 0.000122
      EPNAME     Attempts      Calls Seconds
      HCPSRC00          1          1 0.000116
      HCPSRC04          0          0 0.000000
Ready;

Messages

HCP002E Invalid operand - operand
HCP013E Unknown entry point name entry cannot be associated with an exit point requiring resolution
HCP376E Unknown entry point name entry cannot be associated with an exit point requiring resolution
HCP2773I Entry point name name is unknown at this time; processing continues
HCP6704E Missing token at end of line
HCP6706E {Invalid entry point name - name | Invalid CP Exit number - exit}
HCP6709E Too many items specified - item