REFRESH USEREXIT command
Use the type-2 REFRESH USEREXIT command to refresh the user exit modules that are defined in the USER_EXITS section of the DFSDFxxx member. When the command is processed, IMS rereads the DFSDFxxx member and processes the USER_EXITS section.
Subsections:
Environment
The following table lists the environments (DB/DC, DBCTL, and DCCTL) from which the REFRESH command and keywords can be issued.
| Command / keywords | DB/DC | DBCTL | DCCTL |
|---|---|---|---|
| REFRESH USEREXIT | X | X | X |
| TYPE | X | X | X |
| MEMBER | X | X | X |
Syntax
Keywords
The following keyword is valid for the REFRESH USEREXIT command:
- TYPE(exit_type)
- Specifies the user exit type or types that you want to be refreshed. You can specify a single
user exit type or a list of user exit types separated by commas. The valid user exit types are the following:
- AOIE
- Type-2 Automated Operator User Exit
- BSEX
- Build Security Environment user exit
- ICQSEVNT
- IMS CQS Event user exit
- ICQSSTEV
- IMS CQS Structure Event user exit
- IMSMON
- IMS Monitor user exit
- INITTERM
- Initialization/Termination user exit
- LOGEDIT
- Log Edit user exit
- LOGWRT
- Logger user exit
- NDMX
- Non-Discardable Messages user exit
- OTMAIOED
- OTMA Input/Output Edit user exit
- OTMAYPRX
- OTMA Destination Resolution user exit
- OTMARTUX
- OTMA Resume TPIPE Security user exit
PGMCREAT
- PGMCREAT user exit
- PPUE
- Partner Product user exit
- RASE
- Resource Access Security user exit
- RESTART
- Restart user exit
If an exit type is specified more than once, it is refreshed only once and no error message is issued.
Restriction:The FASTMON user exit type is not refreshable. It is invalid if
specified in the TYPE() parameter of the REFRESH USEREXIT command. - MEMBER(suffix)
- Specifies a 1- to 3-alphanumeric character value that represents the suffix to a DFSDFxxx member
name. The identified DFSDFxxx member is read in and parsed for the EXITDEF statements for the
requested user exit types. If the keyword is not specified, the DFSDFxxx member specified for system
initialization is used as the default. The DFSDFxxx member specified on system initialization can be
determined from message DFS1929I on the system console or log. The command fails if
the MEMBER keyword is specified with an invalid xxx value or if the DFSDFxxx member is not
found.
This keyword is optional. Normally, the DFSDFxxx member specified on system initialization should be the only one available. The purpose of this keyword is to provide the capability of having the command point to an alternate DFSDFxxx member (different from the system default) for test purposes. Outside of testing, IMS expects the MEMBER keyword to be omitted.
Note: These changes are not saved across a restart. If you refresh your user exits from a DFSDFxxx member that is not the member specified on IMS initialization and you do not update your initialization DFSDFxxx member, the user exit changes will be lost when IMS restarts.If the MEMBER parameter is specified without any value (MEMBER()), it is treated as if MEMBER is not specified. The DFSDFxxx member specified for initialization will be used.
Usage notes
You can issue this command only through the Operations Manager (OM) API.
The output of this command is defined in XML and is available to automation programs that communicate with OM.
- Reads the DFSDFxxx member and process the USER_EXITS section of the DFSDFxxx member.
- Loads the user exit modules specified in the USER_EXITS section for the exit types specified in the command.
- Updates the internal IMS control block with pointers to the new user exit modules. Any subsequent calls to the user exit modules will now call the new modules.
- When the processing has completed in the old exit modules, the old modules will be deleted.
IMS loads the new user exit modules before deleting the old modules. If an error occurs during this process (for example, a module could not be loaded), IMS fails the command for the particular user exit type and leaves the current modules of the user exit type in effect. All modules of the specified user exit type must be loaded successfully for the command to complete successfully.
If your IMSplex has multiple IMS systems, you can refresh the user exit modules in all of the IMS systems in the IMSplex by using the default routing for the command. This sends the REFRESH USEREXIT command to all of the IMS systems in the IMSplex and the user exit modules are refreshed in each of the IMS systems. If the refresh fails on one or more IMS systems, you must resolve the problem that caused the command to fail and reenter the command.
- To add a user exit type, insert EXITDEF statements into the USER_EXITS section of the DFSDFxxx member for the user exit type you want to add and then enter the REFRESH USEREXIT command for that exit type. If the user exit has an initialization function, the user exit is called with the initialization function before the user exit is made available to IMS.
- To delete a user exit type, remove the EXITDEF statements from the USER_EXITS section of the DFSDFxxx member for the user exit type you want to delete and then enter the REFRESH USEREXIT command for that exit type.
- To migrate an existing user exit, specify the exit routines on the EXITDEF parameter in the USER_EXITS section of the DFSDFxxx member and then enter the REFRESH USEREXIT command for that exit type.
Refreshes are performed at the exit type level, so when an exit routine of a certain exit type is modified, every exit routine of that exit type is refreshed.
Certain messages contain the short
form of the command to which the message refers. Because the REFRESH USEREXIT
command does not have a short form, the first four characters of the command (REFR)
are specified in the message. These four characters are also used to define the command
security.
Output fields
The following table shows the REFRESH USEREXIT output fields. The columns in the table are:
- Short label
- Contains the short label that is generated in the XML output.
- Long label
- Contains the long label generated in the XML output.
- Keyword
- Identifies the keyword on the command that caused the field to be generated. N/A (not applicable) appears for output fields that are always returned.
- Scope
- Identifies the scope of the output field.
- Meaning
- Provides a brief description of the output field.
| Short label | Long label | Keyword | Scope | Meaning |
|---|---|---|---|---|
| CC | CC | N/A | N/A | Completion code for the line of output. The completion code is always returned. |
| CCTXT | CCText | N/A | N/A | Completion code text that briefly explains the meaning of the non-zero completion code. |
| MBR | MbrName | N/A | N/A | IMSplex member that built the output line. Member name is always returned. |
| TYPE | ExitType | TYPE | LCL | User exit type requested by the REFRESH USEREXIT command. User exit type is always returned. |
| NAME | ModName | N/A | LCL | Exit routine name that was loaded by this REFRESH USEREXIT command. |
Return, reason, and completion codes
The return and reason codes that can be returned as a result of the REFRESH USEREXIT command are standard for all commands entered through the OM API. For a list of the codes and their meaning, see CSLOMCMD: command request.
The following table contains the return, reason, and completion codes for the REFRESH USEREXIT command. Included in the tables is a brief explanation of the codes.
| Return code | Reason code | Meaning |
|---|---|---|
| X'00000000' | X'00000000' | The REFRESH USEREXIT command completed successfully. |
| X'00000004' | X'00001024' | The REFRESH USEREXIT command completed successfully and a message was issued. |
| X'00000008' | X'00002014' | The DFSDFxxx suffix specified in the MEMBER parameter contains an invalid character. |
| X'0000000C' | X'00003000' | The REFRESH USEREXIT command was successful for at least one user exit type. The REFRESH command was not successful for one or more user exit types. The completion code indicates the reason for the error with the user exit type. The completion codes that can be returned by the REFRESH command are listed in Table 4. |
| X'0000000C' | X'00003004' | The REFRESH USEREXIT command was not successful for any of the user exit types specified. The completion code indicates the reason for the error with the user exit type. The completion codes that can be returned by the REFRESH command are listed in Table 4. |
| X'00000014' | X'00005004' | The REFRESH USEREXIT command processing terminated, because a DFSOCMD response buffer could not be obtained. |
| X'00000014' | X'00005FFF' | The REFRESH USEREXIT command processing terminated because of an internal error. |
Errors that are unique to the processing of this command are returned as completion codes. A completion code is returned for each action against an individual resource.
The following table contains completion codes that can be returned on a REFRESH USEREXIT command.
| Completion code | Meaning |
|---|---|
| 0 | The REFRESH USEREXIT command completed successfully for the user exit type. |
| 92 | An Error was encountered while processing the REFRESH USEREXIT command. Check the messages that are returned with the command output for additional information about the error. |
| 148 | The specified user exit type was successfully deleted and a message was issued. |
| 14E | The specified user exit type is deleted and will no longer be called. |
| 14F | The specified user exit type could not be added because there was no EXITDEF for the user exit type in the DFSDFxxx member or because no log record types existed in the DFSVSMxx member (message DFS4586E). |
Examples
The following are examples of the REFRESH USEREXIT command:
Example 1 for REFRESH command
TSO SPOC input:
REFRESH USEREXIT TYPE(ICQSEVNT)TSO SPOC output:
ExitType ModName MbrName CC
ICQSEVNT DFSCQEX0 SYS3 0
ICQSEVNT DFSCQEX1 SYS3 0
ICQSEVNT DFSCQEX2 SYS3 0 OM API input:
<imsout>
<ctl>
<omname>OM1OM </omname>
<omvsn>1.5.0</omvsn>
<xmlvsn>20 </xmlvsn>
<statime>2012.061 20:33:01.174845</statime>
<stotime>2012.061 20:33:01.330060</stotime>
<staseq>C9344A682C43D7AA</staseq>
<stoseq>C9344A685228CD2C</stoseq>
<rqsttkn1>USRT002 10123301</rqsttkn1>
<rc>00000000</rc>
<rsn>00000000</rsn>
</ctl>
<cmd>
<master>SYS3 </master>
<userid>USRT002 </userid>
<verb>REFR</verb>
<kwd>USEREXIT </kwd>
<input>REFRESH USEREXIT TYPE(ICQSEVNT) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="TYPE" llbl="ExitType" scope="LCL" key="YES" len="8"
dtype="CHAR" align="left" />
<hdr slbl="NAME" llbl="ModName" scope="LCL" key="YES" len="8"
dtype="CHAR" align="left" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" key="NO" len="4"
dtype="CHAR" align="left" />
<hdr slbl="CC" llbl="CC" scope="LCL" key="NO" len="4" dtype="INT"
align="right" />
<hdr slbl="CCTXT" llbl="CCText" scope="LCL" sort="n" key="0"
scroll="yes" len="*" dtype="CHAR" align="left" skipb="yes" />
</cmdrsphdr>
<cmdrspdata>
<rsp>TYPE(ICQSEVNT) NAME(DFSCQEX1) MBR(SYS3) CC( 0) </rsp>
<rsp>TYPE(ICQSEVNT) NAME(DFSCQEX2) MBR(SYS3) CC( 0) </rsp>
<rsp>TYPE(ICQSEVNT) NAME(DFSCQEX0) MBR(SYS3) CC( 0) </rsp>
</cmdrspdata>
</imsout>
Explanation: ICQSEVNT exit types are refreshed.
Example 2 for REFRESH command
TSO SPOC input:
REFRESH USEREXIT TYPE(PGMCREAT)TSO SPOC output:
ExitType ModName MbrName CC
PGMCREAT DFSDFPX0 IMS1 0