News
Abstract
An enhancement has been made to IBM Enterprise COBOL for z/OS to add a new function code 11 to the Vendor Interface routine IGZXAPI.
The new function code 11 supports querying dynamic-length elementary item (DLEI) attributes.
Content
Technical Note of APAR PH18644
Updates in the LE Vendor Interface Guide
The following updates apply to Language Environment Vendor Interface, Chapter 17 COBOL-specific vendor interfaces, the section on IGZXAPI.
1. Chapter 17. COBOL-specific vendor interfaces
> IGZXAPI – COBOL file and runtime information query routine
In the Syntax section, add the two new entries highlighted in blue to the R15 return code table.
Syntax
void IGZXAPI
R1 (input)
Points to the parameter area.
R13 (input)
Points to a save area.
R14 (input)
Is the return address.
R15 (input)
Is the entry point address of IGZXAPI.
(output)
The data structure (XINFO or XINFO8) is populated. Registers R2-R14 remain unchanged.
R15 (output)
Is the return code upon return from the routine.
The following table lists the possible return codes and their descriptions:
|
Return code |
Description |
|
-1 |
COBOL internal control areas are corrupted. For function code 1 and 4, this means the File Control Block is corrupted. |
|
-2 |
COBOL internal file information area is corrupted. |
|
-3 |
The length of the input parameter information structure is too short. |
|
-4 |
The input DSA does not belong to a program compiled with COBOL V5 or later compilers. |
|
-5 |
The input Entry Point is invalid, or does not belong to a program compiled with COBOL V5 or later compilers. |
|
-6 |
COBOL internal control area associated with the program to be queried is corrupted. |
|
-11 |
COBOL internal control area associated with the dynamic-length elementary item to be queried is corrupted. |
|
-12 |
Pointer to XINFO structure is zero.
|
|
-99 |
The function code is not valid. |
|
0 |
The call returns successfully. |
|
1 |
The file to be queried or updated is not found. |
2. Chapter 17. COBOL-specific vendor interfaces
> IGZXAPI – COBOL file and runtime information query routine
After the subsection “Layout of the heap storage address table” and before “Layout of the information structure”, add a new subsection “Dynamic-Length Elementary Item (DLEI) Attribute Query” with the following:
Dynamic-Length Elementary Item (DLEI) Attribute Query
To query the properties of a dynamic-length elementary item. The DSECT XINFO11 is the information structure to communicate with the runtime information routine. The output of this query is valid until the next COBOL statement of the queried program is executed. The caller should take note of the following data fields:
XCAA11Q
In AMODE 64 this is an input field. In AMODE 31 this field should be set to zero. It is the address of the Language Environment CAA control block containing the COBOL program.
XWKA11Q
In AMODE 64 this is an input field. In AMODE 31 this field should be set to zero. It is the address of a 2048 byte work area provided by the caller (for use within IGZXAPI). This work area can be allocated anywhere, above or below the bar.
XIADR11Q (AMODE 64 only) / XIADR11X (AMODE 31 only)
This is an input field. It is the address of the dynamic-length elementary item to be queried. In AMODE 31 the high 4 bytes of XIADR11Q should be set to zero.
XCB11Q (AMODE 64 only) / XCB11X (AMODE 31 only)
Optional. This is an input field, and when specified it is the address of a callback function. This is required when the given DLEI address (XIADR11Q or XIADR11X) is not in the current address space of the caller doing the query. In this case, IGZXAPI may not have access to the COBOL program. IGZXAPI will call the callback function to perform storage accesses. The usage and prototype of this callback function is the same as the callback_p parameter in Language Environment's __fnwsa function. In AMODE 31 the high 4 bytes of XCB11Q should be set to zero.
The callback function is entered in the same AMODE when IGZXAPI is called. On entry R13 points to a save area of 72 bytes (for AMODE 31) or 144 bytes (for AMODE 64). R1 points to a parameter area with the following equivalent function prototype:
void * (*callback_p)(void* data_p, size_t data_l);
data_p – Pointer to the start of the required data.
data_l – The number of bytes of data required. data_l will never exceed 16 bytes.
If (*callback_p)() cannot pass back the complete data requested, it
must not return to this routine.
Set this field to zero if a callback function is not required.
All fields below XCB11X are output fields from the routine.
3. Chapter 17. COBOL-specific vendor interfaces
> IGZXAPI – COBOL file and runtime information query routine
In the subsection “Layout of the information structure for AMODE 31”, append the new information structure below to the end:
*
* 1 2 3 4 5 6 7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
XINFO11 DSECT
XFNCOD11 DS F Input: Function code, =11 for a dynamic
* length elementary item descriptor query
FILLR110 DS CL4 reserved
XSIG11 DS F X'C0B00603'(output)
XVER11 DS H Version of this structure block (output)
XLEN11 DS H Input: Length of this data structure, 128
XFLGS011 DS CL8 Reserved, set to zero by caller
FILLR111 DS CL8 Reserved, set to zero by caller
FILLR112 DS CL8 Reserved, set to zero by caller
XCAA11Q DS AD Input: AMODE64 Address of the LE CAA
* Set XCAA11Q to zero in AMODE31
XWKA11Q DS AD Input: AMODE64 Address of 2048 bytes work area
* Set XWKA11Q to zero in AMODE31
*
XIADR11Q DS AD Input: AMODE64 Address of DLEI
ORG XIADR11Q
DS CL4 Reserved
XIADR11X DS A Input: AMODE31 Address of DLEI
*
XCB11Q DS AD Input: AMODE64 Callback func pointer (optional)
ORG XCB11Q
DS CL4 Reserved
XCB11X DS A Input: AMODE31 Callback func pointer (optional)
*
XDLFL011 DS CL4 Reserved
FILLR113 DS CL4 Reserved
*
XBFLN11Q DS FD AMODE64 Length of data at XBFAD11Q (output)
ORG XBFLN11Q
DS CL4 Reserved
XBFLN11X DS F AMODE31 Length of data at XBFAD11X (output)
XMXSZ11Q DS FD AMODE64 Allocated buffer size (output)
ORG XMXSZ11Q
DS CL4 Reserved
XMXSZ11X DS F AMODE31 Allocated Buffer size (output)
XLIMT11Q DS FD AMODE64 DLEI LIMIT value (output)
ORG XLIMT11Q
DS CL4 Reserved
XLIMT11X DS F AMODE31 DLEI LIMIT value (output)
XBFAD11Q DS AD AMODE64 Address of data (output)
ORG XBFAD11Q
DS CL4 Reserved
XBFAD11X DS AL4 AMODE31 Address of data (output)
*
XDLVER11 DS H DLEI Version (output)
FILLR114 DS CL6 Reserved
XDLGRW11 DS H DLEI Growth factor (output)
FILLR115 DS CL6 Reserved
XDLFST11 DS F DLEI Initial allocation size (output)
FILLR116 DS CL4 Reserved
*
* 1 2 3 4 5 6 7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
4. Chapter 17. COBOL-specific vendor interfaces
> IGZXAPI – COBOL file and runtime information query routine
In the subsection “Layout of the information structure for AMODE 64”, append the new information structure below to the end.
*
* 1 2 3 4 5 6 7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
XINFO11 DSECT
(Refer to the "Layout of the information structure for AMODE 31”)
*
*
-~-~- E N D -~-~-
Related Information
Was this topic helpful?
Document Information
Modified date:
04 December 2019
UID
ibm11105731