Provide capability to share UEPTSTOK

Due to processing by IBM, this request was reassigned to have the following updated attributes:
Brand - Servers and Systems Software
Product family - Transaction Processing
Product - CICS Transaction Server

For recording keeping, the previous attributes were:
Brand - WebSphere
Product family - Transaction Processing
Product - CICS Transaction Server

Thanks Stan. Yes the recommendation for use UEPTSTOK has been made via DOC apar PM55372. This will be rolled into the next refresh of the information center.

      The doc apar states:
      
The CICS Transaction Server for z/OS V4.2 Customization Guide (SC34-7161-00) will be updated as follows. A new heading entitled "UEPTSTOK" will be added after the end of the section headed "DFHUEPAR standard parameters" on page 10: "UEPTSTOK UEPTSTOK is an exit-specific parameter that is passed on a number of user exit points. Such exit-specific parameters are described with the individual exits in the section "Global user exit points (in alphabetical order)" on page 31.
UEPTSTOK is set to address the EISEXITT field (the task lifetimetoken in the EIS). The expectation is that this field is set to address some storage that is used by the exits for the task. As such, this task lifetime storage can potentially be shared between different exit programs for the life of a task.
UEPTSTOK provides the address of a 4-byte area that can be used to pass information between successive user exit requests. For example, if you need to pass information between successive invocations of the XFCREQ exit, you can use UEPTSTOK to do so.
Unless exit programs cooperate in their usage of UEPTSTOK, unpredictable results can occur when it is used to address exit-specific data.
An approach for sharing this token by multiple exit programs is as follows.
The UEPTSTOK token is the first of a chain of addresses, the subsequent editions of which are at the front of each piece of storage chained. Exit programs acquire storage and chain the addresses of this storage from UEPTSTOK.
Bytes 0-3 of each piece of storage is a pointer to the next piece of storage chained. Bytes 4-11 contain the name of the exit program which acquired the storage (or some other constant identifying whose storage it is).
Exit programs that wish to use UEPTSTOK should implement this mechanism, to ensure that the field can be shared between multiple exit programs being invoked by the same task.
Typically, exit programs will detect that there is not a currently chained piece of storage for their specific use when driven for the first time by a task. This will make them acquire and add a piece of storage to the chain addressed by UEPTSTOK.
When adding a piece of storage to the chain it may be done to the front or end of the chain. What matters is that the chain is updated to reflect the newly added storage address and exit identifier."

There are APARs available for VT 1.2 and 2.1 (PM55226 and PM55277 respectively) that follow the technique described in doc APAR PM55372. This technique is also used by CA in their DataCom product, which highlighted the need for a mechanism to share UEPTSTOK. Programatically, it make little difference whether a new process is added to the head or the tail of the chain. If there is a compelling reason to add it to the head as opposed to the tail, PM55372, the VT and DataCom APARs become invalid.

Stan,
I don't quite see what your corrections are trying to do.
Possibly my original explanation wasn't clear enough.

There are two use cases here.
1) Add new control block for the first instance of a glue provided by vendor V
2) Find the control block in a subsequent instance of a glue provided by vendor V

If the glue doesn't know if it is the first instance it might need to do use case 2 before 1 to find out.

Use Case 1 - Add a new control block

For this we need to add a control block to a link list pointed to by the pointer in UEPTSTOK.
The easier way of doing this is to add it to the head of the chain, hence my proposal

1) Create a control block GLUETKN in the above format in CICS Key (Task Storage)
2) Set HEADER to your product id
3) Set NEXTTOK to current value pointed to by UEPTSTOK
4) Set the value pointed to by UEPSTOK to the address of GLUETKN

As the value pointed to by UEPTSTOK is initially 0, this means that the chain is null terminated.

Use Case 2 - Find your control block

1) If the value pointed to by UEPTSTOK is 0 the chain is empty, your control block is not found
2) Address the control block with this pointer
3) If the HEADER is your product id then your control block is found
4) If NEXTTOK is 0 you have reached the end of the chain, your control block is not found
5) Address the control block to the pointer value in NEXTTOK and repeat from step 3


I think that in Use Case 1, your correction will only handle the case of the first control block.
I don't understand why in Use Case 2 you are updating the chain. Only a search is required.

This is not quite what has been discussed. Here are the corrections:


Convention when setting UEPTSTOK
3) Set NEXTTOK in the new area to 0
4) Set UEPTSTOK to the address of new area

Convention when using UEPTSTOK
3) Set NEXTTOK in last area to the address of the new area
4) Set NEXTTOK in the new area to 0

Whatever change was implemented would require a change to the GLUE using the field. Therefore the simplest solution, which would apply to all releases of CICS, would be to document a standard technique for using UEPSTOK.

We could document the following recommendation for using a link list to manage UEPSTOK.

User exits that used this field should point to a control block in the format
GLUETKN DSECT
NEXTTOK DS A
HEADER DS CL8


Convention when setting UEPTSTOK:
1) Create a control block in the above format in CICS Key
2) Set HEADER to your product id
3) Set NEXTTOK to current UEPTSTOK value
4) Set UEPSTOK to address of control block

Convention when using UEPTSTOK:
If UEPTSTOK non zero, scan through the UEPTSTOK looking for a HEADER which matches your product id, or NEXTTOK is zero.

Would this be an acceptable solution to you.

Colin Penfold
CICS Development