Using the services
There are 28 callable services available for task synchronization:
- Allocate_Pause_Element – IEAVAPE, IEAVAPE2, IEA4APE, or IEA4APE2
- Deallocate_Pause_Element – IEAVDPE, IEAVDPE2, IEA4DPE, or IEA4DPE2
- Pause – IEAVPSE, IEAVPSE2, IEA4PSE, or IEA4PSE2
- Pause_Multiple_Elements– IEAVPME2 or IEA4PME2
- Release – IEAVRLS, IEAVRLS2, IEA4RLS, or IEA4RLS2
- Retrieve_Pause_Element_Information - IEAVRPI, IEAVRPI2, IEA4RPI, or IEA4RPI2
- Test_Pause_Element - IEAVTPE or IEA4TPE
- Transfer – IEAVXFR, IEAVXFR2, IEA4XFR, or IEA4XFR2
To use Pause, Release, and Transfer, a program must first allocate a PE by calling the Allocate_Pause_Element service. In response, the system allocates a PE and returns a pause element token (PET) that identifies the pause element (PE).
- The PE has been used to pause (through Pause or Transfer) and release (through Release or Transfer) a work unit
- A paused work unit has been released through an asynchronous ABEND.
When you are finished with the PE, call the Deallocate_Pause_Element service to return the PE to the system. If a work unit is asynchronously ABENDed while it is paused, the system itself invalidates the PE, and it cannot be reused for pause requests. Thus, return an invalidated PE to the system as soon as possible by a call to Deallocate_Pause_Element.
Though the PE remains allocated until you deallocate it, you can use a PET only once, to pause and release a work unit. When you specify a PET on a successful call to the Pause service or to pause a work unit through a successful call to the Transfer service, the system invalidates the input PET and returns an updated PET to identify the PE. Use the updated PET to reuse the PE or to deallocate the PE.
/* Common variables */ |
|
Dcl PET char(16); |
|
Workunit #1 | Workunit #2
|
/* Workunit #1 variables */ | /* Workunit #2 variables */
Dcl Auth1 fixed(32); | Dcl Auth2 fixed(32);
Dcl RC1 fixed(32); | Dcl RC2 fixed(32);
Dcl Updated_pet char(16); | Dcl RelCode binary(24);
Dcl RetRelCode binary(24); |
|
Auth1 = IEA_AUTHORIZED; | Auth2 = IEA_AUTHORIZED;
. | .
. | .
. | .
/* Allocate a Pause Element */ |
Call IEAVAPE (RC1,Auth1,PET); |
|
/* Pause Workunit #1 */ |
Call IEAVPSE (RC1,Auth1,PET, |
Updated_PET,RetRelCode); |
|
/*processing pauses until released*/ | RelCode = '123';
| /* Release Workunit #1 */
| Call IEAVRLS (RC2,Auth2,PET,
. | RelCode);
. |
. |
/* Deallocate the pause element */ |
Call IEAVDPE (RC1,Auth1, |
Updated_PET); |
The Pause, Release, and Transfer services also provide a release code field that is particularly useful when a dispatchable unit might be released before it is paused. The program that calls the Release service can set a release code.
Release code is returned to the invoker of Pause and can be used to communicate the reason for the release.
/* Common variables */ |
|
Dcl PET char(16); |
|
Workunit #1 | Workunit #2
|
/* Workunit #1 variables */ | /* Workunit #2 variables */
Dcl Auth1 fixed(32); | Dcl Auth2 fixed(32);
Dcl RC1 fixed(32); | Dcl RC2 fixed(32);
Dcl Updated_PET char(16); | Dcl RelCode binary(24);
Dcl RetRelCode binary(24); |
|
Auth1 = IEA_AUTHORIZED; |
|
/* Allocate a Pause Element */ |
Call IEAVAPE (RC1,Auth1,PET); |
. | Auth2 = IEA_AUTHORIZED;
. | RelCode='123';
. |
| /* Release Workunit #1 */
| Call IEAVRLS (RC2,Auth2,PET,
| RelCode);
/* Pause Workunit #1 */ | .
Call IEAVPSE (RC1,Auth1,PET, | .
Updated_PET,RetRelCode); | .
|
/*check release code and continue */ |
. |
. |
. |
/* Deallocate the pause element */ |
Call IEAVDPE (RC1,Auth1, |
Updated_PET); |
If you make a release request (through Release or Transfer) specifying a PET that identifies a PE that has not yet been used to pause a task or SRB, the system marks the PE as a prereleased PE. If a program tries to pause a work unit using a prereleased PE, the system returns control immediately to the caller; it does not pause the work unit. Instead, it resets the PE. As soon as a PE is reset, it can be reused for another Pause and Release, but, as stated earlier, you use the returned updated PET for each subsequent reuse of the PE.
- Release a paused dispatchable unit and transfer control directly to the released dispatchable unit
- Pause the current dispatchable unit, release a paused dispatchable unit, and transfer control directly to the released dispatchable unit
Figure 3 shows an example of using the Transfer service to release a dispatchable unit without pausing the current work unit.
- The current pause element token (CurrentDuPet in Figure 3) identifies the allocated pause element that Transfer is to use to pause the current dispatchable unit (the caller of the Transfer service). When you do not need to pause the current dispatchable unit, you set this token to binary zeros, as shown in Figure 3.
- The updated pause element token (UPET2 in Figure 3), which the system returns when you specify a current pause element token. You need this updated token to reuse the pause element on a subsequent Pause or Transfer or to deallocate the pause element. If you set the current token to binary zeros, as done in Figure 3, the contents of the updated pause element token are not meaningful.
- The target token (TargetDuPET in Figure 3) identifies the allocated pause element that Transfer is to use to release a dispatchable unit. In Figure 3, it contains the PET that identifies the PE used to pause Workunit #1.
/* Common variables */ |
|
Dcl PET char(16); |
|
Workunit #1 | Workunit #2
|
/* Workunit #1 variables */ | /* Workunit #2 variables */
Dcl Auth1 fixed(32); | Dcl Auth2 fixed(32);
Dcl RC1 fixed(32); | Dcl RC2 fixed(32);
Dcl UPET1 char(16); | Dcl CurrentDuRelCode char(3);
Dcl RetRelCode binary(24); | Dcl CurrentDuPET binary(24);
. | Dcl UPET2 char(16);
. | Dcl TargetDuPET char(16);
. | Dcl TargetDuRelCode binary(24);
Auth1 = IEA_AUTHORIZED; |
/* Allocate a Pause Element */ | Auth2 = IEA_AUTHORIZED;
Call IEAVAPE (RC1,Auth1,PET); | .
| .
/* Pause Workunit #1 */ | .
Call IEAVPSE (RC1,Auth1,PET,UPET1, | TargetDuRelCode = '123';
RetRelCode); | /* no pause-set token to zeros */
| CurrentDuPet ='';
| TargetDuPET = PET
/*processing pauses until transfer*/ |
| /* Transfer to Workunit #1 */
| Call IEAVXFR (RC2,Auth2,
| CurrentDuPET,UPET2,
| CurrentDuRelCode,
| TargetDuPET,
| TargetDuRelCode);
/*processing continues */ | .
| .
/* Deallocate the Pause Element */ | .
Call IEAVDPE (RC1,Auth1,UPET1); |