Vision Report Documentation Update: CALL function Addressability Clarification - Calling Programs in AMODE 24/31
Article ID: 212697
Updated On:
Products
Issue/Introduction
When building a parameter list and a pointer is used to make changes to a data area that area is sometimes changed. Unexpected results could occur. Sometimes a S0C7 or U3336 abend can be experienced (Among other inaccuracies)
Environment
Vision Report 16.1
z/OS or VSE any level
Resolution
The following documentation change is provided to be inserted on page 3-19 of the Vision Report Reference Guide. The title heading is CALL
Before the change
CALL Loads a user coded routine at compilation time (VSE) or execution
time (MVS) and passes control to that routine each time the executing VISION:Report program passes through the CALL statement. Optionally, CALL passes to the user routine the address of user-specified data areas and literals.
After the change
After CALL Loads a user coded routine at compilation time (VSE) or execution time (MVS) and passes control to that routine each time the executing VISION:Report program passes through the CALL statement. Parameters specified on the CALL statements are a "CALL By Value", which means a temporary copy of the parameters are passed, (rather than the actual address of the parameters referred to as a "CALL By Reference"). VISION:Report internally builds a parameter list of the parameters listed on the CALL statement. When returning from the call, parameter changes are copied into the actual parameters. If a "CALL By Reference" is required, a parameter list or PARMLIST can be built within the VISION:Report program with the use of the SET PTx command and the SET PTx SAVE command. The SET PTx command will capture the actual address of the VISION:Report storage field, and SET PTx SAVE command will move the address into one of the PARMLIST's parameter fields. The actual addresses of the VISION:Report working storage fields never change and the PARMLIST need only be built once. The actual addresses are all above the line so the calling must be in AMODE 31, (unlike a "CALL By Value" where the parameters are passed in the same AMODE as the calling program). VISION:Report internally builds a parameter list. Therefore, you have a parameter list that points to another parameter list. The calling program must take this into account.
CALL Loads a user coded routine at compilation time (VSE) or execution time (MVS) and passes control to that routine each time the
executing VISION:Report program passes through the CALL statement.
Optionally, CALL passes to the user routine the address of user-specified data areas and literals, provided the called program is linked as AMODE 31. If not, VISION:Report does a CALL By Value by copying the parameter list data areas and literals to storage below the line and passes a copy of user-specified data areas and literals to the called program in storage below the line. Copy changes replace the actual user-specified data areas on the return call to VISION:Report.
An example follows:
CALL BY VALUE
Following are the areas being passed to the CALL
EQU HEADER-AREA WST1-50 /* HEADER AREA
EQU TABLE-AREA WST2500-11500 /* TABLE AREA
EQU WORK-AREA WST100-500 /* WORK AREA
EQU DATA-AREA WST600-2100 /* DATA AREA
The CALL statement will include all storage areas being passed, as follows:
CALL EXTPGM
HEADER-AREA
TABLE-AREA
WORK-AREA
DATA-AREA
CALL BY REFERENCE
Following are the areas being passed to the CALL
EQU HEADER-AREA WST1-50 /* HEADER AREA
EQU TABLE-AREA WST2500-11500 /* TABLE AREA
EQU WORK-AREA WST100-500 /* WORK AREA
EQU DATA-AREA WST600-2100 /* DATA AREA
Following is the PARMLIST that will be used to pass the actual addresses
EQU PARMLIST WST080-095 /* PARMLIST
EQU PARHDRA WST080-083-B /* POINTER TO HEADER AREA
EQU PARTBLA WST084-087-B /* POINTER TO TABLE AREA
EQU PARWRKA WST088-091-B /* POINTER TO WORK AREA
EQU PARDATA WST092-095-B /* POINTER TO DATA AREA
The SET command, followed by another SET command with the SAVE option, would be required to store the actual storage area addresses into the parameter list, as follows:
Note: The SET commands here need only be done once, since the VISION:Report storage addresses never change.
SET PTA HEADER-AREA /* OBTAIN HEADER AREA ADDRESS WITH THE SET COMMAND
SET PTA SAVE PARHDRA /* MOVE HEADER AREA ADDRESS TO THE PARM LIST
SET PTA TABLE-AREA /* OBTAIN TABLE AREA ADDRESS WITH THE SET COMMAND
SET PTA SAVE PARTBLA /* MOVE TABLE AREA ADDRESS TO THE PARM LIST
SET PTA WORK-AREA /* OBTAIN WORK AREA ADDRESS WITH THE SET COMMAND
SET PTA SAVE PARWRKA /* MOVE WORK AREA ADDRESS TO THE PARM LIST
SET PTA DATA-AREA /* OBTAIN DATA AREA ADDRESS WITH THE SET COMMAND
SET PTA SAVE PARDATA /* MOVE DATA AREA ADDRESS TO THE PARM LIST
The CALL statement will then reference the established PARMLIST rather than the individual storage blocks, as follows:
CALL EXTPGM
PARMLIST
Feedback
