Stage 1 Submit Exit
Beginning with Connect:Direct 6.4, there are two Stage 1 Submit exits. First, the legacy APF Unauthorized Stage 1 Submit exit (DMCXSUBM) is called. If it sets RC>0, then the submit is disallowed. Otherwise, the APF Authorized Stage 1 Submit exit (DMCXSUBA) is called. If it sets RC>=8, then the submit is disallowed. Otherwise, the Submit is allowed. Both exits are optional and for each its absence is the same as setting RC=0. The Stage 1 Submit exits execute in the API address space when a SUBMIT command is processed and in the DTF address space when a SUBMIT statement is encountered in a Process. Observe the following restrictions and requirements:
- The IBM Connect:Direct Stage 1 Submit exits are implemented as executable load modules.
- You must give the load modules either Names or Aliases of DMCXSUBM and DMCXSUBA for the Unauthorized and Authorized exits, respectively.
- Both should be link-edited as RENT, REUS and AMODE 31.
- The Unauthorized exit (DMCXSUBM) can be link-edited with an authorization code of 0, since it does not execute APF Authorized. The Authorized exit (DMCXSUBA) must be link-edited with an authorization code of 1, otherwise it will not be called in an APF authorized environment for every type of caller.
- The Unauthorized exit (DMCXSUBM) must come from an authorized load library. The Authorized exit (DMCXSUBA) must come from an authorized concatenation.
- In TSO there are many ways to make the load modules available to the IUI. You can have them in
the LINKLIST, a STEPLIB, TSOLIB, or ISPLLIB DD, or in LIBDEF ISPLLIB. Not all methods work when
using the Stage 1 Submit exits. The following shows various combinations and the issues they can run
into.
--------------------------------------------------------------------------------------------------------- | LINKLIST | STEPLIB | TSOLIB | ISPLLIB | LIBDEF | Results | | | | | | ISPLLIB | | | | | | | | | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD+EXIT | | | | | OK - preferred | | | PROD+EXIT | | | | OK | | | | PROD+EXIT | | | OK | | | | | PROD+EXIT | | OK - see note 1 | | | | | | PROD+EXIT | OK - see note 1 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD+EXIT | | | | PROD+EXIT | OK | | | PROD+EXIT | | | PROD+EXIT | OK | | | | PROD+EXIT | | PROD+EXIT | OK | | | | | PROD+EXIT | PROD+EXIT | OK - see note 1 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD+EXIT | | | | non-C:D | OK | | | PROD+EXIT | | | non-C:D | OK | | | | PROD+EXIT | | non-C:D | OK | | | | | PROD+EXIT | non-C:D | OK - see note 1 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD | EXIT | | | | OK - Use to test exits via STEPLIB | | PROD | | EXIT | | | OK - Use to test exits via TSOLIB | | PROD | | | EXIT | | OK - Use to test exits via ISPLLIB | | PROD | | | | EXIT | OK - Use to test exits via LIBDEF ISPLLIB | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | PROD | | | | EXIT | OK | | | PROD | | | EXIT | Exits not found - see Note 2 | | | | PROD | | EXIT | Exits not found - see Note 2 | | | | | PROD | EXIT | Exits not found - see Note 2 | |-----------|-----------|-----------|-----------|-----------|-------------------------------------------| | EXIT | | | | PROD | OK - see note 1 | | | EXIT | | | PROD | Exits not found - see Note 3 | | | | EXIT | | PROD | Exits not found - see Note 3 | | | | | EXIT | PROD | Exits not found - see Note 3 | --------------------------------------------------------------------------------------------------------- Where: non-C:D - does not contain C:D load modules or the Stage 1 exit(s) PROD - contains all C:D product load modules except the exit(s) EXIT - contains only Stage 1 exits (e.g. DMCXSUBA and DMCXSUBM) PROD+EXIT - contains both C:D product load modules and the Stage 1 exit(s) Notes: 1. In these cases, the exits are found either in LIBDEF ISPLLIB or in the normal MVS Load Module search sequence starting with ISPLLIB. But when the Authorized Stage 1 Submit exit (DMCXSUBA) is invoked, it executes in an APF authorized environment, which means the exit is running under a TCB under IKJEFT02, not ISPTASK, and so MVS cannot search the LIBDEF ISPLLIB or the ISPLLIB DD for load modules called by DMCXSUBA. MVS can and does search any TSOLIB and STEPLIB DDs, and finally the LINKLIST. The distributed Authorized Stage 1 Submit exit attempts to use the C:D DISPLAY macro to issue debug messages. DISPLAY does an MVS LOAD on DMGRAT. But DMGRAT is non-reentrant and was loaded earlier by the IUI when it was running non-APF authorized. MVS rejects the in-storage copy of DMGRAT as unsafe, and tries to load a fresh copy. If MVS cannot find a fresh copy in the TSOLIB DD, STEPLIB DD or the LINKLIST it issues the error message: CSV027I REQUESTED MODULE DMGRAT NOT ACCESSED, APF PROTECTION INADEQUATE Fortunately, this merely prevents the exit from issuing debug messages. Other than that and the above message issued to the TSO user, the exit works normally. The CSV027I error message can be suppressed using the TSO command PROFILE NOWTPMSG. Alternately, the sample exit DGAXSUBA has a switch to turn off the debug messages, thereby preventing the problem. This problem does not occur with the Unauthorized exit. 2. In these cases, the IUI LOADs a C:D module (DMDYNALO) using DCB=(LIBDEF-ISPLLIB-DCB) and gets S806-04. This is because with LOAD DCB=(LIBDEF-ISPLLIB-DCB) MVS searches that DCB concatenation, and if the module is not found, skips any ISPLLIB, TSOLIB, and STEPLIB DDs, and resumes searching with the LINKLIST. If you are running another instance of the IUI on another ISPF logical screen, then that instance's in-storage copy of DMDYNALO will be found. But if there is only one instance, then not finding DMDYNALO causes DMISTART to clear the pointer to the LIBDEF ISPLLIB DCB and not use it again. Subsequent searches for load modules are done with DCB=0, thus bypassing LIBDEF ISPLLIB. Thus the exits in LIBDEF ISPLLIB will not be found (unless they’re also in the LINKLIST). 3. In these cases, DMISTART LOADs DMDYNALO using DCB=(LIBDEF-ISPLLIB-DCB) and finds it. From there on, the IUI load modules use LOAD with DCB=(LIBDEF-ISPLLIB-DCB). When this form of LOAD is used, the MVS load module search sequence skips searching the ISPLLIB, TSOLIB, and STEPLIB DDs. If the exits are in one of those DDs, they will not be found (unless they’re also in the LINKLIST - A new sample exit member, DGAXSUBA, is supplied which is configurable for multiple security products and profile naming schemes. It also has several other configuration options. It must be linked with AC=1 and a name or alias of DMCXSUBA into an APF authorized library. The APF authorized library should be the same one the rest of the product is installed into. A new sample JCL member, DGAXSTGA, is supplied to assemble and link DGAXSUBA and assign it an alias of DMCXSUBA.
- In order to call the new APF authorized exit from the IUI (or other TSO caller), DMCXSUBA must be included in SYS1.PARMLIB(IKJTSOxx) AUTHTSF list.
- In order to call the new APF authorized exit from DGADBATC (DMBATCH), DGADBATC now executes as an APF authorized jobstep program (linked with AC=1). Thus, DGADBATC must be loaded from an APF authorized concatenation.
Authorized Stage 1 Submit Exit Processing Return Codes and Messages
The following table shows the possible return codes and messages that can occur during Authorized Stage 1 Submit Exit processing, their outcomes, and possible User Action.