ALERT: Some images may not load properly within the Knowledge Base Article. If you see a broken image, please right-click and select 'Open image in a new tab'. We apologize for this inconvenience.

Vision Report Documentation Update: CALL function Addressability Clarification - Calling Programs in AMODE 24/31

book

Article ID: 212697

calendar_today

Updated On:

Products

Vision:Report

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