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.
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=DEFINEHexadecimal 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 not in the range of X'41' to X'FE'. 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=DELETEHexadecimal Return Code |
Hexadecimal Reason Code |
Meaning and Action |
---|
00 |
00 |
Meaning: CPF completed successfully. Action:
None.
|
04 |
04 |
Meaning: Program error. The prefix contained
characters not in the range of X'41' to X'FE'. 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=REDEFINEHexadecimal Return Code |
Hexadecimal Reason Code |
Meaning and Action |
---|
00 |
00 |
Meaning: CPF completed successfully. Action:
None.
|
04 |
04 |
Meaning: Program error. The prefix contained
characters not in the range of X'41' to X'FE'. 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 '
.
.
.
|