CPF - Execute form

Use the execute form of the CPF macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.

Syntax

The execute form of the CPF macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CPF.

CPF

␢	One or more blanks must follow CPF.

	Valid parameters (Required parameters are underlined):
REQUEST=DEFINE	PREFIX, OWNER, SCOPE, FAILDISP, REMOVE
REQUEST=DELETE	PREFIX, CURSYS
REQUEST=REDEFINE	PREFIX, OWNER, CURSYS, NEWSYS

,PREFIX=`prefix addr`	`prefix addr`: RX-type address or register 2-12.

,OWNER=`owner addr`	`owner addr`: RX-type address or register 2-12.

,SCOPE=SYSPLEX	Default: SCOPE=SYSPLEX
,SCOPE=SYSTEM

,FAILDISP=PURGE	Default: FAILDISP=PURGE
,FAILDISP=SYSPURGE
,FAILDISP=RETAIN

,REMOVE=NO	Default: REMOVE=NO
,REMOVE=YES

,CURSYS=`sys name`	`sys name`: RX-type address or register 2-12.

,NEWSYS=`sys addr`	`sys addr`: RX-type address or register 2-12.

,MF=(E, `list addr`)	`list addr`: RX-type address or register 2-12

The parameters are explained as follows:

REQUEST=DEFINE

REQUEST=DELETE

REQUEST=REDEFINE

Specifies the desired command prefix facility function to be performed. You can specify only one function at a time. The three functions are:

DEFINE: Creates the definition for a new command prefix.
DELETE: Deletes an existing command prefix.
REDEFINE: Defines a new receiving system for a given prefix, and a new owner name, if needed.

,PREFIX=prefix addr

Specifies the address of a required 8-byte field containing the command prefix. If the prefix is less than 8 characters, it must be left-justified and padded with blanks.

,OWNER=owner addr

Specifies the address of an 8-byte field containing a name that identifies the subsystem owning the command prefix (for example, JES2, JES3, IMS). If the name is less than 8 characters, it must be left-justified and padded with blanks.

,SCOPE=SYSPLEX

,SCOPE=SYSTEM

Specifies the range of systems to which a command with this prefix can be routed for execution. The values are:

SYSPLEX: The command issued can be routed to another system in the sysplex for execution. If SCOPE is not specified, this is the default.
Note: If the installation has defined the security profile MVS.CPF.ROUTE.CHECK in the OPERCMDS class, the issuer of the command requires sufficient authority to the MVS.ROUTE.CMD.system to route the command to a different system in the sysplex.
SYSTEM: The command issued will execute in the system on which the command is entered.

,FAILDISP=PURGE

,FAILDISP=SYSPURGE

,FAILDISP=RETAIN

Specifies the failure disposition of the prefix being defined. Any one of the following can be specified:

PURGE: The command prefix is automatically deleted when the receiving system is removed from the sysplex, or the defining address space terminates. If the FAILDISP is not specified, this value is the default.
SYSPURGE: The command prefix is automatically deleted when the receiving system is removed from the sysplex, but not when the defining address space terminates.
RETAIN: The command prefix will persist even if a system is removed or the address space of the routine processing the command terminated. In this case, the owning subsystem is responsible for redefining the command prefix for another system or deleting the command prefix, respectively.

,REMOVE=YES

,REMOVE=NO

Specifies whether the command prefix is removed from the command text prior to being executed on the receiving system. REMOVE=NO indicates the command prefix and the command are presented to the receiving system. If the REMOVE parameter is not specified, this is the default. REMOVE=YES indicates the command prefix is removed from the command before it is presented to the receiving system.

,CURSYS=sys name

Specifies the address of an 8-byte field containing the name of the system for which the prefix was defined. The system is the system on which the command will be processed. Issue the DISPLAY XCF command to obtain a list of the names of systems in the sysplex. If the system name is less than 8 bytes, it must be left-justified and padded on the right with blanks. The default is the name of the system on which the CPF macro is invoked.

,NEWSYS=sys addr

Specifies the address of an 8-byte field containing the name of the new system to which commands with this prefix should be routed in the event that the system specified on CURSYS fails. If the system name is less than 8 bytes, it must be left-justified and padded on the right with blanks. The default is the name of the system on which the CPF macro is invoked.

,MF=(E,list addr)

Specifies the execute form of CPF.

list addr specifies the area that the system uses to store the parameters.

ABEND codes

None.

Return and reason codes

When the CPF macro with REQUEST=DEFINE returns control to your program, GPR 15 contains a hexadecimal return code and GPR 0 contains a hexadecimal reason code.

Table 1. Return and Reason Codes for the CPF Macro with REQUEST=DEFINE
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: CPF completed successfully. Action: None.
00	04	Meaning: Environmental error. You specified DEFINE with SCOPE=SYSPLEX, but the system was in XCF-local mode. Action: Ensure that you are running in a sysplex, or change the SCOPE parameter. Retry the request.
04	04	Meaning: Program error. The prefix contains characters that are not supported. For a list of supported characters, see Assigning a prefix in z/OS MVS Programming: Authorized Assembler Services Guide. Action: Correct the prefix and retry the request.
04	08	Meaning: Program error. The OWNER parameter on the DEFINE request contained characters not in the range of X'41' to X'FE'. Action: Correct the OWNER parameter and retry the request.
08	08	Meaning: Program error. You specified DEFINE for a prefix that already exists. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: If you specified the wrong prefix, correct the problem and retry the request.
08	0C	Meaning: Program error. You specified DEFINE with a prefix that is a subset of an existing prefix. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Refer to prefix subset requirements. Correct the problem and retry the request.
08	10	Meaning: Program error. You specified DEFINE with a prefix that was a superset of an existing prefix. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Refer to prefix subset requirements. Correct the problem and retry the request.
0C	None.	Meaning: System error. A broadcast of an updated CPF table failed, or an abend occurred. Action: If an abend occurred, register 0 contains the abend code. Record the return code and supply it to the appropriate IBM® support personnel.

When the CPF macro with REQUEST=DELETE returns control to your program, GPR 15 contains a hexadecimal return code and GPR 0 contains a hexadecimal reason code.

Table 2. Return and Reason Codes for the CPF Macro with REQUEST=DELETE
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: CPF completed successfully. Action: None.
04	04	Meaning: Program error. The prefix contains characters that are not supported. For a list of supported characters, see Assigning a prefix in z/OS MVS Programming: Authorized Assembler Services Guide. Action: Correct the prefix and retry the request.
08	04	Meaning: Environmental error. You specified DELETE, but the prefix was not found in the CPF table. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Correct the problem and retry the request.
08	1C	Meaning: Program error. You specified DELETE, but no CPF table exists. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Determine whether the CPF table should exist.
0C	None.	Meaning: System error. A broadcast of an updated CPF table failed, or an abend occurred. Action: If an abend occurred, register 0 contains the abend code. Record the return code and supply it to the appropriate IBM support personnel.

When the CPF macro with REQUEST=REDEFINE returns control to your program, GPR 15 contains a hexadecimal return code and GPR 0 contains a hexadecimal reason code.

Table 3. Return and Reason Codes for the CPF Macro with REQUEST=REDEFINE
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: CPF completed successfully. Action: None.
04	04	Meaning: Program error. The prefix contains characters that are not supported. For a list of supported characters, see Assigning a prefix in z/OS MVS Programming: Authorized Assembler Services Guide. Action: Correct the prefix and retry the request.
04	08	Meaning: Program error. The OWNER parameter on the DEFINE request contained characters not in the range of X'41' to X'FE'. Action: Correct the OWNER parameter and retry the request.
04	0C	Meaning: Program error. You specified REDEFINE for a prefix that was defined with FAILDISP=PURGE. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Correct the problem and retry the request.
08	04	Meaning: Environmental error. You specified REDEFINE, but the prefix was not found in the CPF table. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Correct the problem and retry the request.
08	14	Meaning: Program or environmental error. You specified REDEFINE, but the NEWSYS parameter specified a system not in the sysplex. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Wait for the specified system to join the sysplex, or determine if you specified an incorrect system name. Make any necessary corrections and retry the request.
08	18	Meaning: Program error. You redefined a prefix and targeted it for another system in the sysplex. However, that system had the same prefix already defined. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Correct the problem and retry the request.
08	1C	Meaning: Program error. You specified REDEFINE, but no CPF table exists. CPF internally issues the DISPLAY OPDATA command which displays the command prefixes defined for subsystems in the sysplex. Action: Determine whether the CPF table should exist.
0C	None.	Meaning: System error. A broadcast of an updated CPF table failed, or an abend occurred. Action: If an abend occurred, register 0 contains the abend code. Record the return code and supply it to the appropriate IBM support personnel.

Example

Define a prefix that causes all commands issued with that prefix to be sent to system cvtsname for processing.

 CPF MF=(L,CPFLIST)
     ⋮
 CPF REQUEST=DEFINE,
     PREFIX=CVTSNAME,
     OWNER=OWNER,
     SCOPE=SYSPLEX,
     FAILDISP=PURGE,
     REMOVE=YES,
     MF=(E,CPFLIST)
     ⋮
     OWNER DC CL8'CONSOLE '
     ⋮