Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
SA23-1372-00

The COFRETRI macro enables an application using VLF to obtain a copy of a VLF object on behalf of an end user. Before issuing COFRETRI, or any VLF macro, you need to understand the information on using the virtual lookaside facility (VLF) that appears in z/OS MVS Programming: Authorized Assembler Services Guide.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state, with PSW key 0-7
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

Before you issue COFRETRI to retrieve an object on behalf of a user, you must issue COFIDENT to identify the user. COFIDENT relates to COFRETRI in the following ways:

COFIDENT returns the user token you must supply on COFRETRI.
COFIDENT establishes the major-name search order for this user.
COFIDENT defines whether COFRETRI must be issued under a task with a home ASID that matches the home ASID of the issuer of COFIDENT (COFIDENT was issued with SCOPE=HOME), or whether the task invoking COFRETRI can have a different home ASID (COFIDENT was issued with SCOPE=SYSTEM).

Restrictions

None.

Input register information

Before issuing the COFRETRI macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-14: Unchanged
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-14: Unchanged
15: Used as a work register by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The standard form of the COFRETRI macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede COFRETRI

COFRETRI

␢	One or more blanks must follow COFRETRI

MINOR=`minor`	`minor`: Rx-type address or register (2) - (12).

,UTOKEN=`utoken`	`utoken`: Rx-type address or register (2) - (12).

,TLIST=`tlist`	`tlist`: Rx-type address or register (2) - (12).

,TLSIZE=`tlsize`	`tlsize`: Rx-type address or register (2) - (12).

,OBJSIZE=`objsize`	`objsize`: Rx-type address or register (2) - (12).

,CINDEX=`cindex`	`cindex`: Rx-type address or register (2) - (12).

,RETCODE=`retcod`	`retcod`: Rx-type address or register (2) - (12).

,RSNCODE=`rsncod`	`rsncod`: Rx-type address or register (2) - (12).

Parameters

The parameters of the standard form are explained as follows:

MINOR=minor

Is a required parameter that identifies the minor name of the object. VLF assumes that the length of the minor name is the same as that specified on the MINLEN parameter when the COFDEFIN macro was issued to define the class. If the class of objects was defined with major name to PDS name correspondence, then the minor name length is 8.

,UTOKEN=utoken

Is the required 16-character user token that identifies the user for whom you are retrieving a VLF object. VLF returned the user token when you issued the COFIDENT macro to identify the user to VLF.

,TLIST=tlist

Is a required parameter that defines the target area list. The target area list describes target areas into which consecutive areas of the object are to be stored. The target area list consists of a fullword containing the number of target areas, followed by three words for each area:

A fullword that contains the ALET that currently addresses the target area. An ALET of 1, referencing the SASN of the caller, or ALETs referencing entries on the PASN access list of the caller, are not allowed.
A fullword that contains the 31-bit address of the data for the target area.
A fullword that contains the length of the target area.

An address of 0 signifies that VLF is to ignore the specified length; that is, VLF is not to retrieve that part of the object. The maximum number of parts is 16.

,TLSIZE=tlsize

Is a required parameter, a fullword that contains the size (in bytes) of the target area list.

,OBJSIZE=objsize

Is a required parameter, a fullword that VLF is to use to return the size (in bytes) of the object it retrieves.

,CINDEX=cindex

Is a required parameter, a one-byte field that VLF is to use to return the concatenation index of the major name associated with the object it retrieves. The index is the zero-origin relative number of the major name for the object in the major name list of the user retrieving the object. This list is the one that was supplied when the COFIDENT macro identified the user to VLF.

For concatenated partitioned data sets, the CINDEX value is the same as the “K” (concatenation index) value returned when a BLDL macro is issued to locate a member.

,RETCODE=retcod

Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15. If you specify a storage location, it must be on a fullword boundary.

,RSNCODE=rsncod

Specifies the location where the system is to store the reason code. The reason code is also in GPR 0. If you specify a storage location, it must be on a fullword boundary.

ABEND codes

None.

Return and reason codes

When the COFRETRI macro returns control to your program, GPR 15 (and retcod, if you coded RETCODE) contains one of the following hexadecimal return codes. When the COFRETRI macro returns control to your program, GPR 0 (and rsncod, if you coded RSNCODE) contains one of the following hexadecimal reason codes.

Table 1. Return and Reason Codes for the COFRETRI Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: The VLF object was successfully retrieved. OBJSIZE contains the size of the VLF object. CINDEX contains the zero-origin concatenation index number for the object (the zero-origin relative entry number in the major name list supplied on the COFIDENT macro). Action: None.
02	00	Meaning: Program error. A VLF object has been retrieved that might be the correct object for the user, but the object might also exist in earlier major names in the user's major name list. OBJSIZE contains the size of the VLF object. CINDEX contains the zero-origin concatenation index number for the object (the zero-origin relative entry number in the major name list supplied on the COFIDENT macro). Action: Issue the BLDL macro to determine whether the object returned by VLF is the correct object based on the user's major name search order. If the object does exist on DASD in an earlier name in the user's major name search order, then take two steps: Use the alternate method to acquire the object for the user Issue the COFCREAT macro to create the VLF object.
04	00	Meaning: Program error. The VLF object was retrieved, but the target areas did not receive the entire object. OBJSIZE contains the size of the VLF object. CINDEX contains the zero-origin concatenation index number for the object (the zero-origin relative entry number in the major name list supplied on the COFIDENT service). Action: Increase the size of the target area, then issue COFRETRI again.
06	00	Meaning: Program error. A VLF object has been retrieved that might be the correct object for the user, but the object might also exist in earlier major names in the user's major name list. Additionally, the target areas did not receive the entire object. OBJSIZE contains the size of the VLF object. CINDEX contains the zero-origin concatenation index number for the object (the zero-origin relative entry number in the major name list supplied on the COFIDENT service). Action: Use the same steps as for return code 02 to determine if the object is the correct one. If it is, increase the size of the target area, then issue COFRETRI again.
08	00	Meaning: Program error. VLF could not find a matching object to retrieve. Action: Use an alternate method to acquire the object for the user. Then issue COFCREAT to create the VLF object.
08	04	Meaning: Program error. A retrieve was attempted for a major name that has changed or been deleted. Action: Use an alternate method to acquire the object for the user. Then issue COFCREAT to create the VLF object.
0A	00	Meaning: Program error. The parameter list cannot be accessed. Action: Make necessary corrections to ensure that the parameter list ALET is on the dispatchable unit access list (DU-AL) and rerun the program.
0C	00	Meaning: Program error. The class to which the user is identified is not currently defined. Action: Define the class with COFDEFIN and retry the operation.
0E	00	Meaning: Program error. The user has insufficient authorization. To retrieve an object for the class, the caller must be a task running in supervisor state or with PKM allowing key 0-7. Action: Use an alternate method to acquire the object for the user.
10	00	Meaning: Program error. An unknown user token was specified. The most likely reason for this is that the user has been removed from VLF identification because the user's major name list has changed. It is also possible you have not supplied the correct token. Action: In either case, you must issue the COFIDENT macro; you must reidentify the user to VLF before you can retrieve objects for the user. Also, ensure that the UTOKEN passed to the COFRETRI macro is valid.
14	00	Meaning: Environmental error. VLF incurred a program check when it tried to access the TLIST. You might, for example, have specified a larger target area to VLF than was actually available or specified a target area the user had no authority to modify. Action: Rerun the program. If the problem persists, specify a smaller TLSIZE parameter for the TLIST.
18	00	Meaning: Program error. Action: Ensure that all parameters passed to the COFRETRI macro contain valid data. Make necessary corrections in the application, and rerun the program.
18	02	Meaning: Program error. TLSIZE is greater than the maximum allowable size, or the number of target areas is greater than 16. Action: Ensure that the first word of the TLIST, which contains the number of target areas, is not greater than 16. Make corrections and rerun the program.
18	0B	Meaning: Program error. The object specified on MINOR cannot be accessed using the specified ALET. The ALET is a SASN ALET, or the ALET is not on the dispatchable unit access list (DU-AL). Action: Make necessary corrections to ensure that the MINOR ALET is on the dispatchable unit access list (DU-AL) and rerun the program.
18	0C	Meaning: Program error. TLIST cannot be accessed using the specified ALET. The ALET is a SASN ALET, or the ALET is not on the dispatchable unit access list (DU-AL). Action: Make necessary corrections to ensure that the TLIST ALET is on the dispatchable unit access list (DU-AL) and rerun the program.
18	0D	Meaning: Program error. A target area in the target list cannot be accessed using the specified ALET. The ALET is a SASN ALET, or the ALET is not on the dispatchable unit access list (DU-AL). Action: Make necessary corrections to ensure that the target area ALET is on the dispatchable unit access list (DU-AL) and rerun the program.
28	00	Meaning: Environmental error. Action: Record the return and reason codes and supply them to the appropriate IBM® support personnel.
2C	nnnn	Meaning: System error. nnnn is the reason code. Action: Record the return and reason codes and supply them to the appropriate IBM support personnel.