There is an ocean of different MVS services created to make life easier for us mainframe geeks. Unfortunately their primary interface is assembler which reduces their usability immensely for most of us including me. A colleague made me aware of the socalled name/token MVS service and to my big surprise I discovered that it is callable directly from COBOL, PL/I, REXX and other programming languages which conforms to standard linkage conventions.

The name/token service makes you capable of creating small global variables which lives across almost anything. MVS administrates your variables and all you have to do is to create variables with a unique name. It is very similar to ISPF pool variables. The name/token service operates with two categories of variables: task (TCB) related variables and address space related variables. Task related variables lives as long as your task lives and address space variables lives for the duration of your address space. Depending on your needs you must choose between one of these two categories. Please be aware that CICS has its own definition of tasks which is completely different from the MVS definition. I will strongly advise you not to use the name/token service from CICS even though it works just fine.

And here is how to use the name/token service in PL/I:

DCL ntType fixed bin(31);
DCL ntName char(16);
DCL ntToken char(16);
DCL ntLife fixed bin(31);
DCL ntRC fixed bin(31);
DCL ieantcr EXT ENTRY OPTIONS(ASM);
DCL ieantrt EXT ENTRY OPTIONS(ASM);
DCL ieantdl EXT ENTRY OPTIONS(ASM);

ntType = 1;
ntLife = 0;
ntName = 'MYMVSVARIABLE';
ntToken = 'KILROY WAS HERE';
CALL ieantcr(ntType, ntName, ntToken, ntLife, ntRC);
if ntRC = 0
then do;
  put skip list(ntname !! ' created');
  ntToken = '';
  CALL ieantrt(ntType, ntName, ntToken, ntRC);
  if ntRC = 0
  then do;
    put skip list(ntname !! ' = ' !! ntToken);
    CALL ieantdl(ntType, ntName, ntRC);
    if ntRC = 0
    then
      put skip list(ntname !! ' deleted');
  end;
end;

I hope those of you who are more familiar with COBOL, REXX or other languages are able to translate the above into equivalent pieces of code or else feel free to contact me.

The variable ntType is set to 1 for task related variables and 2 for address space related variables. The variable ntName is assigned a unique name which no one else in the task or address space is using. Stay away from names beginning with 'A' to 'I' and hex '00' as they are reserved by MVS. I normally use the program name in the first eight bytes and something representative in the next eight. The variable ntToken is then assigned the value of the variable. There are only 16 bytes available. If you need more you have to use other means. The variable ntLife must always be zero. The variable ntRC is set by the called service to 0 when the call is successful and 4 when ntName is either non-existing or already exists. Please note that there is no service to update the value of an existing name/token. You must delete it and create it again with the new value.

The service call IEANTCR creates a variable with the name in ntName having the value in ntToken. IEANTRT copies the value of the variable in ntName to ntToken. IEANTDL deletes the variable in ntName.

A way of storing more than 16 bytes by using only one token is to save the address of an area containing the data in the token value. This method is only usable for task related variables as areas allocated by programs typically disappears when the task executing the program terminates. Therefore it is quite complicated (but not impossible) to create global address space related variables with more than 16 bytes of information. To do it you have to allocate storage which is not freed when the task terminates.