Many years ago I promised someday to write a tip about the ISPF functions VDEFINE and VDELETE. These two functions are special, because they can only be used from compiling programming languages through the ISPLINK interface. The VDEFINE function is used to create a connection between an ISPF variable and a variable in your program, VDELETE removes it again. But first I will show you how to call VDEFINE and VDELETE from COBOL and PL/I. Remember to examine RETURN-CODE in COBOL and pliretv() in PL/I after a call to ISPLINK. The value zero indicates that it was a successful call. Let us start with COBOL:
And then PL/I:
These examples clearly shows the advantages of PL/I over COBOL, apart from the fact that in PL/I it is important to specify the trailing blanks if you use constant values in the call to ISPLINK as in this example. STG(ISPFVAR) returns the length of ISPFVAR in this cae 10. It is a really good idea to use the STG-function here, because then you only need to adjust the length in the declaration if needed. The specified calls to VDEFINE creates the connection to an ISPF variable called ISPFVAR. Using the same name for the variable in the program is not a requirement, but it helps understanding what is going on. In the call to VDEFINE you specify to ISPF how the variable is defined in the program. ISPF will try to convert to the specified format. You are for instance allowed to use FIXED as a variable-type, but it requires that the contents of the ISPF variable is purely consisting of numieric digits, otherwise you will run into unexpected results.
If more than one program or module in the same execution creates connection to the same ISPF variable, they will each receive their own connection. It is important to remove the connection again with one VDELETE for each VDEFINE. If not a program may retrieve a wrong value for the ISPF variable especially if it is updated. ISPF might also think that the variable in the program is still available after program termination if you forget to VDELETE, which may lead to unexpected abends.
I have used the phrase "ISPF variables" several times without telling you what they are. If you for instance want to fill in or or get the value of a field in an ISPF panel, it is done using an ISPF variable. The same is true for columns in an ISPF table or variables in an ISPF skeleton. One of the interesting features is the access to the value of various Z-variables which are predefined ISPF variables. Please be aware that an ISPF variable is not the same as a variable in REXX or CLIST. You cannot access the value of a variable in REXX or CLIST using VDEFINE. In REXX and CLIST the connection between an ISPF variable and a REXX or CLIST variable is created automatically. This makes it much easier to use ISPF from REXX or CLIST compared to COBOL and PL/I.
If you execute a VDEFINE of a Z-variable and cannot understand why you do not get access to its value, you need to execute a VGET in order to retrieve the value. You can avoid using VGET by adding a parameter to the VDEFINE call and give it the value COPY. By the way you can VDEFINE and VDELETE many variables at the same time. Follow the links for VDEFINE and VDELETE above to learn more. If you wonder what a name-list is, it is either a single ISPF variablename as specified in my examples or a list of ISPF variablenames surrounded by parenthesis like (ISPFVAR1 ISPFVAR2).