QUERY USEREXIT command

Use the type-2 QUERY USEREXIT command to display information about the user exits that are defined in the USER_EXITS section of the DFSDFxxx member of the IMS PROCLIB data set. Information about user exits that are not specified in the USER_EXITS section of the DFSDFxxx member is not displayed in the output of the QUERY USEREXIT command.

Subsections:

Environment
Syntax
Keywords
Usage notes
Output fields
Return, reason, and completion codes
Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) from which the QUERY USEREXIT command and keywords can be issued.

Table 1. Valid environments for the QUERY USEREXIT command and keywords
Command / keywords	DB/DC	DBCTL	DCCTL
QUERY USEREXIT	X	X	X
SHOW	X	X	X
TYPE	X	X	X

Syntax

Keywords

The following keywords are valid for the QUERY USEREXIT command:

TYPE()

Specifies the user exit type or types for which you want information displayed. You can specify a single user exit type or a list of user exit types separated by commas. If the SHOW keyword is not specified, only the names of the exit routines for the specified types are returned. The valid user exit types are:

AOIE: Type-2 Automated Operator User Exit
BSEX: Build Security Environment user exit
FASTMON: IMS Fast Monitor 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

SHOW()

Specifies the information about the user exit routines to be returned in the output fields of the command response. The exit type and module name fields are always returned along with the name of the IMS that created the output for the user exit type and the completion code. The valid fields that can be specified are the following:

ALL

All possible output fields are returned.

ACTIVE

The number of currently active instances of the user exit routine. This is a point-in-time number that represents the number of calls to the user exit that are still in progress and have not returned to IMS.

CALLS

The number of calls to the user exit since the last user exit routine refresh. For performance reasons serialization is not obtained when IMS collects this number. For an exit type that can run multiple instances in parallel, this number is an approximation. The maximum value that this field can contain is 4,294,967,295 (2³²-1). When the call count exceeds this value, the field rolls over and starts again from zero.

ENTRYPT

The entry point address of the user exit routine.

ETIME

The total (cumulative) elapsed time in milliseconds spent in the exit module since it was last refreshed. For performance reasons serialization is not obtained when IMS collects this number. For an exit type that can run multiple instances in parallel, this number is an approximation. The maximum value that can be displayed in this field is 2,147,483,647 (2³¹-1). If the elapsed time exceeds this value, 2147483647 is displayed.

LOADPT

The address at which the user exit routine was loaded.

RTIME

The local date and time that the user exit routine was last refreshed (or initially loaded, if no refreshes have occurred). The format of the output field is:

yyyy-mm-dd hh:mm:ss.th

SIZE

The size in bytes of the user exit load routine. This value is displayed in hexadecimal.

TEXT

The 32 bytes starting from offset +04 from the entry point of the exit module, translated to EBCDIC with non-printable characters replaced by periods (.). This is a common location for module identification information. If your user exit routines contain printable identification data at this point in the module, you can use the TEXT option to display that information.

Usage notes

You can issue the QRY USEREXIT command only through the Operations Manager (OM) API.

The output contains an entry for each user exit module within each user exit type specified in the QUERY USEREXIT command. The output of this command is defined in XML and is available to automation programs that communicate with OM.

The QRY USEREXIT command is routed to all IMS systems in the IMSplex as its default routine.

Output fields

The following table shows the QUERY 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.
Non-applicable exits: Identifies the exit types in which the output field is not applicable. The value of the output field will be 0.

Table 2. Output fields for the QUERY USEREXIT command
Short label	Long label	Keyword	Scope	Meaning	Non-applicable exits
ACTIVE	Active	ACTIVE	LCL	Number of active instances of this exit module.	FASTMON
CALLS	Calls	CALLS	LCL	Number of calls to this user exit module since the last refresh.	FASTMON
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 nonzero completion code.
ENTRYPT	EntryPt	ENTRYPT	LCL	The entry point of this user exit module.
ETIME	ElapseTime	ETIME	LCL	The total time spent in this user exit module since the last refresh.	FASTMON
LOADPT	LoadPt	LOADPT	LCL	The load point of this user exit module.
MBR	MbrName	N/A	N/A	IMSPLEX member that built the output line. Member name is always returned.
NAME	ModName	N/A	LCL	User exit module name. User exit module name is always returned.
RTIME	RefreshTime	RTIME	LCL	The time this user exit module was last refreshed.
SIZE	ModSize	SIZE	LCL	The size in hexadecimal of this user exit module.
TEXT	ModuleText	TEXT	LCL	32 bytes from this user exit module translated into EBCDIC.
TYPE	ExitType	TYPE	LCL	User exit type requested by the QUERY command. User exit type is always returned.

Return, reason, and completion codes

The return and reason codes that can be returned as a result of the QUERY USEREXIT command are standard for all commands entered through the OM API.

The following table contains the return, reason, and completion codes for the QUERY USEREXIT command. Included in the tables is a brief explanation of the codes.

Table 3. Return and reason codes for the QUERY USEREXIT command
Return code	Reason code	Meaning
X'00000000'	X'00000000'	The QUERY USEREXIT command completed successfully.
X'00000004'	X'00001010'	The QUERY USEREXIT command is not processed because no user exit routines were found that matched the TYPE parameter.
X'0000000C'	X'00003000'	The QUERY USEREXIT command was successful for at least one user exit type. The QUERY USEREXIT 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 QUERY USEREXIT command are listed in Table 4.
X'0000000C'	X'00003004'	The QUERY 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 QUERY USEREXIT command are listed in Table 4.
X'00000014'	X'00005004'	The QUERY USEREXIT command processing terminated because a DFSOCMD response buffer could not be obtained.
X'00000014'	X'00005FFF'	The QUERY 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 QUERY USEREXIT command.

Table 4. Completion codes for the QUERY USEREXIT command
Completion code	Completion code text	Meaning
0		The QUERY USEREXIT command completed successfully for the user exit routine.
10	NO RESOURCES FOUND	None of the user exit types specified are known to the IMS that processed the command. The user exit types might have been typed in error. Confirm that the user exit types are spelled correctly on the command.

Examples

The following are examples of the QUERY USEREXIT command:

Example 1 for QUERY USEREXIT command

TSO SPOC input:

QRY USEREXIT TYPE(INITTERM) SHOW(CALLS,RTIME)

TSO SPOC output:

Response for: QRY USEREXIT TYPE(INITTERM) SHOW(CALLS,RTIME)          
ExitType ModName  MbrName   CC       Calls RefreshTime                
INITTERM DFSITRX2 SYS3       0           1 2013-04-22 10:20:41.12     
INITTERM DFSITRX0 SYS3       0           1 2013-04-22 10:20:41.12     
INITTERM DFSITRX1 SYS3       0           1 2013-04-22 10:20:41.12

OM API input:

CMD(QRY USEREXIT TYPE(INITTERM) SHOW(CALLS,RTIME))

OM API output:

<imsout>                                               
<ctl>                                                  
<omname>OM1OM   </omname>                              
<omvsn>1.4.0</omvsn>                                   
<xmlvsn>20  </xmlvsn>                                  
<statime>2013.112 17:23:12.064868</statime>            
<stotime>2013.112 17:23:12.065191</stotime>            
<staseq>CB4069B7E1D642A1</staseq>                                 
<stoseq>CB4069B7E1EA75A1</stoseq>                                 
<rqsttkn1>USRT003 10102312</rqsttkn1>                             
<rc>00000000</rc>                                                 
<rsn>00000000</rsn>                                               
</ctl>                                                            
<cmd>                                                             
<master>SYS3    </master>                                         
<userid>USRT003 </userid>                                         
<verb>QRY </verb>                                                 
<kwd>USEREXIT        </kwd>                                       
<input>QRY USEREXIT TYPE(INITTERM) SHOW(CALLS,RTIME) </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" />              
<hdr slbl="CALLS" llbl="Calls" scope="LCL" key="YES" len="10"               
 dtype="INT" align="right" />                                               
<hdr slbl="RTIME" llbl="RefreshTime" scope="LCL" key="no" len="22"          
 dtype="CHAR" align="left" />                                               
</cmdrsphdr>                                                                
<cmdrspdata>                                                                
<rsp>TYPE(INITTERM) NAME(DFSITRX2) MBR(SYS3) CC(   0) CALLS(                
 1) RTIME(2013-04-22 10:20:41.12) </rsp>                                    
<rsp>TYPE(INITTERM) NAME(DFSITRX0) MBR(SYS3) CC(   0) CALLS(                
 1) RTIME(2013-04-22 10:20:41.12) </rsp>                                    
<rsp>TYPE(INITTERM) NAME(DFSITRX1) MBR(SYS3) CC(   0) CALLS(                
 1) RTIME(2013-04-22 10:20:41.12) </rsp>                                    
</cmdrspdata>                                                               
</imsout>

Example 2 for QUERY USEREXIT command

TSO SPOC input:

QRY USEREXIT TYPE(AOIE) SHOW(CALLS,RTIME)

TSO SPOC output:

Response for: QRY USEREXIT TYPE(INITTERM) SHOW(CALLS,RTIME)          
ExitType ModName  MbrName   CC       Calls RefreshTime                
AOIE     DFSAOE00 SYS3       0           1 2013-04-22 10:20:41.12     
AOIE     USREXIT2 SYS3       0           1 2013-04-22 10:20:41.12

OM API input:

CMD(QRY USEREXIT TYPE(AOIE) SHOW(CALLS,RTIME))

OM API output:

<imsout>                                               
<ctl>                                                  
<omname>OM1OM   </omname>                              
<omvsn>1.4.0</omvsn>                                   
<xmlvsn>20  </xmlvsn>                                  
<statime>2013.112 17:23:12.064868</statime>            
<stotime>2013.112 17:23:12.065191</stotime>            
<staseq>CB4069B7E1D642A1</staseq>                                 
<stoseq>CB4069B7E1EA75A1</stoseq>                                 
<rqsttkn1>USRT003 10102312</rqsttkn1>                             
<rc>00000000</rc>                                                 
<rsn>00000000</rsn>                                               
</ctl>                                                            
<cmd>                                                             
<master>SYS3    </master>                                         
<userid>USRT003 </userid>                                         
<verb>QRY </verb>                                                 
<kwd>USEREXIT        </kwd>                                       
<input>QRY USEREXIT TYPE(INITTERM) SHOW(CALLS,RTIME) </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" />              
<hdr slbl="CALLS" llbl="Calls" scope="LCL" key="YES" len="10"               
 dtype="INT" align="right" />                                               
<hdr slbl="RTIME" llbl="RefreshTime" scope="LCL" key="no" len="22"          
 dtype="CHAR" align="left" />                                               
</cmdrsphdr>                                                                
<cmdrspdata>                                                                
<rsp>TYPE(AOIE) NAME(DFSAOE00) MBR(SYS3) CC(   0) CALLS(                
 1) RTIME(2013-04-22 10:20:41.12) </rsp>                                    
<rsp>TYPE(AOIE) NAME(USREXIT2) MBR(SYS3) CC(   0) CALLS(                
 1) RTIME(2013-04-22 10:20:41.12) </rsp>                                                                    
</cmdrspdata>                                                               
</imsout>

Explanation: Information about Initialization/Termination exits is displayed. The information includes the number of calls to the user exit since it was loaded and the date and time that the user exit routine was loaded.

Example 3 for QUERY USEREXIT command

TSO SPOC input:

QRY USEREXIT TYPE(PGMCREAT) SHOW(CALLS,RTIME)

TSO SPOC output:


ExitType ModName  MbrName   CC       Calls      RefreshTime
PGMCREAT DFSDFPX0 IMS1       0           1      2013-04-22 10:20:41.12