Understanding How USER EXITS on the INSERT, UPDATE and DELETE repository commands work.

Document ID : KB000024809
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

The repository permits the use of user exits on some of the repository commands that can be accessed from the OPTIONS or EDIT menus such as the EDIT.INSERT, EDIT.DELETE, EDIT.UPDATE and EDIT.SYNC.commands

This technical document describes how these User Exits work.

Solution:

Repository Commands, such as you see when you click on the EDIT menu item (SELECT, INSERT, UPDATE, DELETE etc) are themselves instances of repository objects, which can themselves be INSERTed, DELETEd and UPDATEd via the repository and which have a STATUS and a version and so forth. This is explained in some detail in the Administrator Guide under 'Working with Commands'.

The repository allows the attachment of User Exits to these commands, as is explained in the Adminstrator Guide under 'Working with User Exits' , and as the screen layout shows, these exits are, from the Repository point of view, simply ATTRIBUTES of the Repository Command object.

SIZE ----------- CURRENT DIALOG: EXTEND ENTITY TYPE: COMMAND ----------MAX 
- FILE EDIT VIEW OPTIONS SYSTEM PROFILE NAVIGATE HELP - 
- LAST ACTION: NOTHING+ 1 OF 1 
- HEADER INFORMATION: 
- WINDOW COMMAND ===> 
- STATUS ===> 
- VERSION NUMBER ===> (0 - 32767) 
- DESCRIPTION ===> 
- ===> 
- COMMAND DEFINITION: 
- WINDOW ===> 
- FUNCTION ===> 
- SUB FUNCTION ===> 
- COMMAND ===> 
- ACTION BAR SEQUENCE ===> 0 (1 - 32767) 
- COMMAND EXIT PROCEDURE: 
- PROCEDURE NAME ===> 
- PROCEDURE TYPE ===> (C-CLIST,P-PANEL,G-PROGRAM) 
- EXECUTION TIME ===> 
- 
----------------------------------------------------------------------------- 

These exits are executed by the ISPF online EDIT (program DBEXCEL) and not the "IO module" or its stored procedures. Therefore these exits are not executed when running any of the batch jobs, your programs that call DBXVLIO or DBXVLI2, nor will they be called from AllFusion Repository for z/OS Webstation Option. Don't forget that these exists require an ISPF environment which only the online ISPF editor provides

The Command 'SYNC'
One area where this distinction leads to confusion is with the additional Repository command "SYNC". SYNC is a command, listed under the EDIT menu the same as INSERT, UPDATE and DELETE, which allows the user to execute multiple instances of these other EDIT commands, while in vertical mode.

Hence, assuming you have a number of entities displayed in Vertical Mode:

COMMAND ===> 
SIZE ------------ CURRENT DIALOG: DB2   ENTITY TYPE: ELEMENT
? FILE EDIT VIEW OPTIONS SYSTEM PROFILE NAVIGATE HELP R40TEST
? 
?           ELEMENT NAME                     STATUS   VER 
?           -------------------------------- -------- ------
u__   1. DISP-SEQ-NUM                     TFSYNC       0 
u__   2. INS-DT                           TFSYNC       0 
d__   3. INS-USER-ID                      TFSYNC       0 
d__   4. LANG-CD                          TFSYNC       0 
i__   5. PARENT-STRUCT-NUM                TFSYNC       1

it would be possible to perform 2 updates, 2 deletes and an insert, simply by setting up the screen as shown and executing EDIT.SYNC from the menu

COMMAND ===> 
SIZE ------------ CUR
? FILE EDIT VIEW OPTI
?      | SELECT     ?
?      | INSERT     ?
?      | UPDATE     ?
?   __ | DELETE     ?
?   __ | DOMAIN     ?
?   __ | MINIEDIT   ?
?   __ | SYNC       ? <<<<<
?   __ | CHGSCR   > ?

Many users, having attached an exit routine to, say, INSERT, mistakenly believe that since "SYNC executes INSERT" , they have nothing more to do and that their exit will execute whichever way INSERT gets executed. This is not correct.

EDIT.SYNC, as the menu above shows, is a separate command, on the same level as INSERT, UPDATE or DELETE and if you want your exit to run when you execute SYNC, you will have to attach it to SYNC as well. Furthermore, assuming the exit in question was only supposed to run when an INSERT was performed, additional code will be required inside the exit itself, to guarantee that the exit only performs the desired actions when SYNC is performing an INSERT.

Repository User Exits (on commands) are coded as either CLISTS or Rexx execs. We provide a special ISPF variable called SYNCACT, which contains the particular action SYNC is going to perform on a given call. By accessing this variable, the user can control the function of the exit when it is being invoked by the SYNC command.

Hence, assuming the purpose of the exit was to keep count of the number of INSERTs performed (via online command) and the exit for the INSERT command itself consisted of:

000001 PROC 0 
000002 CONTROL NOLIST NOMSG NOPROMPT NOCONLIST NOSYMLIST
000003 
000004   ISPEXEC VGET (INSERTS) SHARED 
000005   SET &INSERTS = &INSERTS + 1 
000006   ISPEXEC VPUT (INSERTS) SHARED 
000007 
000008  EXIT 
Then the  exit for the SYNC command would have to be coded as:
 
000001 PROC 0 
000002 CONTROL NOLIST NOMSG NOPROMPT NOCONLIST NOSYMLIST 
000003 
000004   IF &SYNCACT = 'I' THEN + 
000005    DO 
000006       ISPEXEC VGET (INSERTS,SYNACT) SHARED 
000007       SET &INSERTS = &INSERTS + 1 
000008       ISPEXEC VPUT (INSERTS) SHARED 
000009    END 
000010  EXIT 
 
 
The 'INSERTS' variable gets incremented every time SYNC executes an UPDATE or a DELETE as well.