CINFC: Control program interface

This general macro allows ECB-controlled programs to access protected main storage by returning the address of an interface point at execution time. This eliminates reassembly of these programs because of changes in the storage map. Additionally, the CINFC macro provides a convenient way for a real-time program to request update of the file copy of one or more control program keypoint records.

Last updated

Changed in 2023 (information only; no code change).
Changed in 2020 (information only; no code change).
Changed in 2019 (information only; no code change).
Changed for PUT07 (information only; no code change).
Changed for PUT06 (information only; no code change).
Changed for PUT00.

Format

E-type Program

C-type Program

Notes:

¹ The AMODE parameter is not supported for macros called from control program (CP) code. When CP is running, the z/TPF system must be in 64-bit mode.

label

A symbolic name that can be assigned to the macro statement.

R

Specifies the return interface address for an E-type program; leave storage protected.

For a C-type program, specifies the return interface address; leave storage protect key unchanged. All control program services will be by fast path. That is, the macro will always generate inline code for calls by the control program.

W

Specifies the return interface address for an E-type program; allow program to write in protected storage. This option is restricted and requires program authorizations of KEY0 and RESTRICT.

A

Specifies the return interface location address for an E-type program; allow program to write in protected storage. This option is restricted and requires program authorization of KEY0 and RESTRICT.

K

Initiates control program (CP) keypoint update. Specify one or more of the following:

KEYB
KEYD
KEYE
KEY1
KEY2
KEY3
KEY4

LIST

Generates a list of equates only and no executable code.

LITERAL

Generates only a list of literals.

intpt

The symbolic label of the desired interface point, as defined in the CINFC macro. The label is also called a CINFC tag.

For a current list of the CINFC tags refer to the source code for the CINFC macro.

F

The optional fast path. It is valid with the R parameter only. The current protection key will not be changed and the macro will not request service via an SVC.

BSS

The subsystem for which the macro will return the interface point. The defaults depend on whether the calling program is an E-type or part of the control program (C-type).

BSS=,: Specifies that when a null is the value of the parameter (BSS=,), the CE1DBI field (in the ECB) is assumed to contain the subsystem index. This is the default value for E-type programs. This type of invocation is processed by a service routine.
NO: Indicates that for an E-type program, the register specified in the REG parameter is assumed to have the subsystem index to be used to access the CINFC data. This type of invocation expands inline.
For a C-type program, the subsystem ordinal number must be supplied in REG prior to issuing the CINFC macro. The value is multiplied by 4 by CINFC to obtain the offset to the data.
YES: Specifies that the BSS CINFC data will be accessed for an E-type program. This type of invocation expands inline.
For a C-type program, specifies that the value returned in REG will be for the basic subsystem. This is the default value for the control program.
INDEX: Indicates that the subsystem (ordinal) index value will be found in the register specified in the REG parameter. The user must multiply the value by 4 to obtain the offset to the data before calling CINFC.

This parameter is only meaningful in an MDBF environment.

REG=reg1|R14

Specifies the register in which the interface address is to be placed. The default is R14, and R0 may not be specified. In addition, if the 'F' option is not specified, R14 must be specified for the 'REG' parameter.

TABLE

For CP use only and will generate a table of displacements within Keypoint X for all the keypointable keypoints. There will be two entries in the table for each keypointable keypoint: a) a displacement to the keypoint descriptor entry; and b) a displacement to the keypoint core address entry. Any CSECT which calls the CINFC TABLE also needs to call the CX0CK macro to define the symbols used to generate the table.

AMODE

Specifies the format that is used by all address parameters. The valid address format values are:

amodedef: The default value is specified by the AMODE parameter of the BEGIN macro. If the AMODE parameter is not specified on the BEGIN macro, the default value is 31.
31: Specifies that addresses are in 31-bit format.
64: Specifies that addresses are in 64-bit format.

Entry requirements

R9 must contain the address of the ECB being processed (for real-time segments only).
For a CP call in which the parameter BSS=NO is coded, the general register specified by REG must contain the subsystem ordinal number.
When BSS=INDEX is coded, the REG parameter must contain the correct subsystem index value.

Return conditions

Control is returned to the next sequential instruction.
For the R parameter without the fast path option, the requested interface point address is in R14, and the current protection key is set to that of application core.
For the R parameter with the fast path option, the requested interface point address is in R14 or the register specified in REG. The contents of R14 are unknown if the REG parameter specifies a register other than R14.
For the W parameter, the requested interface address is in R14, and the current protection key is set to zero. The original protection key is saved and can be restored when you issue the KEYRC macro with the OKEY=YES parameter coded.
For the A parameter, the requested interface location address is in R14 and the current protection key is set to zero. The address returned is for the subsystem specified by the BSS parameter or CE1DBI. If the value being update is shared it must be changed in each subsystem.
For the K parameter, the update of the indicated keypoints has been scheduled but not completed.
For a C-type program, the contents of R15 are not changed, unless R15 is specified as the return register. For an E-type program, the contents of R15 are unknown, unless the R parameter is used with the fast path option and the REG parameter is R15.

Programming considerations

For information about macro register conventions, see Register conventions.
The CINFC macro requires one, two, or three fullwords of storage. If the SVC is invoked (for parameters R, W, A, and K), the macro expands to use one fullword. For the R parameter with the fast path option, the macro expands to two fullwords, and when BSS=NO is included, the macro expands to three fullwords.
Up to five control program keypoints can be updated with a single macro.
For the R parameter, if F is coded, macro CZ1CP will be invoked if it has not already been called. This is required for addressability to the CINFC table.
The CINFC macro execution can result in a system error and a forced exit of the ECB if an address requested with the W option is not defined in this configuration. that is, the address is zero (0).
If storage protection override is turned on when the CINFC macro is called with the W or A option specified, the override status is saved so that it can be restored by the KEYRC macro with the OKEY=YES parameter specified, and then storage protection override is turned off. See KEYRC–Restore protection key for more information about restoring the storage protection key and storage protection override.
For the K parameter, the keypoint descriptors are altered according to the information contained in the parameter list so that keypoint updating will occur at the next opportunity.
The CINFC K option of this macro can be executed only from the main I-stream. All other invocations of the macro can be executed from any I-stream.

Examples

None.