-DISPLAY FUNCTION SPECIFIC command (Db2)

The -DISPLAY FUNCTION SPECIFIC command displays statistics about external user-defined functions that Db2 applications access.

Abbreviation: -DIS FUNC SPEC

Environment for -DISPLAY FUNCTION SPECIFIC

This command can be issued from a z/OS® console, a DSN session under TSO, a DB2I panel (DB2 COMMANDS), an IMS or CICS® terminal, or a program using the instrumentation facility interface (IFI).

Data sharing scope: Group or member

Authorization for -DISPLAY FUNCTION SPECIFIC

To run this command, you must use a privilege set of the process that includes one of the following authorities for each function:
  • DISPLAY privilege
  • System DBADM authority
  • SYSOPR authority
  • SYSCTRL authority
  • SYSADM authority
If you specify DISPLAY FUNCTION SPECIFIC *.* or schema.partial-name *, you must use a privilege set of the process that includes one of the following authorities:
  • SYSOPR authority
  • SYSCTRL authority
  • SYSADM authority

Db2 commands that are issued from a logged-on z/OS console or TSO SDSF can be checked by Db2 authorization using primary and secondary authorization IDs. Start of changeA logged-on z/OS user ID must be defined in RACF or a similar security server.End of change

If you are using an external security product to authorize usage of DISPLAY FUNCTION SPECIFIC, define SYSOPR as a user to the external security product for those cases in which DISPLAY FUNCTION SPECIFIC SCOPE(GROUP) runs on a remote system and SYSOPR is used as the authorization ID.

Syntax for -DISPLAY FUNCTION SPECIFIC

Read syntax diagramSkip visual syntax diagramDISPLAY FUNCTION SPECIFIC( *.*)(,schema.specific-function-nameschema.partial-name*)SCOPE(LOCALGROUP)

Option descriptions for -DISPLAY FUNCTION SPECIFIC

schema.specific-function-name
Displays information for the specific named function in the specified schema. You cannot specify a function name as you can in SQL; you must use the specific name. If a specific name was not specified on the CREATE FUNCTION statement, query SYSIBM.SYSROUTINES for the correct specific name:
SELECT SPECIFICNAME, PARM_COUNT
  FROM SYSIBM.SYSROUTINES
   WHERE NAME='function_name'
    AND SCHEMA='schema_name';
 
For overloaded functions, this query can return multiple rows.
schema.partial-name*
Displays information for a set of functions in the specified schema.

The specific names of all functions in the set begin with partial-name and can end with any string, including the empty string. For example, schema1.ABC* displays information for all functions with specific names that begin with ABC in schema1.

(*.*)
Displays information for all functions that Db2 applications have accessed since the Db2 subsystem was started.
SCOPE
Specifies the scope of the command.
( LOCAL )
Specifies that the display includes information from only the local member.
(GROUP)
Specifies that the display includes information from all members of the data sharing group.

Usage notes for -DISPLAY FUNCTION SPECIFIC

Displaying information for all functions
If you do not specify a partial or specific function name, Db2 displays information for all functions that Db2 applications have accessed since the Db2 subsystem was started.
Built-in functions or user-defined functions that are sourced on another function
This command does not apply to built-in functions or user-defined functions that are sourced on another function.
Displaying SQL functions

SQL functions are displayed in the DISPLAY FUNCTION SPECIFIC output only if you invoke the function in debug mode. In that case, the WLM environment column in the output contains the WLM environment that you specified for debugging when you created the SQL function.

The DISPLAY FUNCTION output shows the statistics on an SQL function as '0' if the function is under the effect of a STOP FUNCTION command.

Trace information for commands issued with group scope
If this command is issued with options that specify group scope in a Db2 data sharing member, it also runs on all other active members. IFICID 090 trace records for other group members can show that the same command was issued by the SYSOPR authorization ID from the 016.TLPKN5F correlation ID, in addition to the trace records from the member where the original command was issued. See Command scope in Db2 data sharing.

Output for -DISPLAY FUNCTION SPECIFIC

The DSNX975I message displays output from the DISPLAY FUNCTION SPECIFIC command. The output from this command has the following general structure:

DSNX975I csect-name - DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-

------ SCHEMA = schema
FUNCTION STATUS ACTIVE QUED  MAXQ TIMEOUT FAIL WLM_ENV
function status active qued maxq timeout fail wlm_env
function status active qued maxq timeout fail wlm_env
function status active qued maxq timeout fail wlm_env


------ SCHEMA = schema
csect-name ALL FUNCTIONS STARTED FOR THIS SCHEMA.
FUNCTION STATUS ACTIVE QUED  MAXQ TIMEOUT FAIL WLM_ENV
function status active qued maxq timeout fail wlm_env
function status active qued maxq timeout fail wlm_env
function status active qued maxq timeout fail wlm_env


------ SCHEMA = schema
FUNCTION STATUS ACTIVE QUED  MAXQ TIMEOUT FAIL WLM_ENV
function status active qued maxq timeout fail wlm_env
function status active qued maxq timeout fail wlm_env
function status active qued maxq timeout fail wlm_env
 FUNCTIONS begin - end STOP (act)
...

csect-name ALL OTHER FUNCTIONS IN OTHER SCHEMAS STOPPED act

DISPLAY FUNCTION SPECIFIC REPORT COMPLETE

The output that is displayed varies depending on the qualifying external user-defined functions. Error messages might also be included in the output.

The following information can be provided in the output:

csect-name
The name of the control section that issued the message.
SCHEMA = schema
The schema name for the functions that are included in the output.

The schema name and lines that follow are repeated as many times as needed to satisfy the DISPLAY FUNCTION SPECIFIC request.

FUNCTION function
The name of the external function.

One line of output is included for each requested function.

STATUS status
The status of the function. The status can be any of the following values:
STARTED
The function can accept SQL statement requests.
STOPABN
The function was stopped because of a previous abnormal termination of the function application. SQL statement requests for the function are rejected.
STOPQUE
The function was stopped. SQL statement requests for the function are queued until the function is started or the timeout interval that is defined by the STORTIME subsystem parameter expires.
STOPREJ
The function was placed in this status by the STOP SPECIFIC FUNCTION command with the ACTION(REJECT) option. SQL statement requests for the function are rejected.

If the function is in any of the stopped states, you can use the START SPECIFIC FUNCTION command to start the function.

ACTIVE active
The number of Db2 agents that are currently running this function.
QUED qued
The number of Db2 agents that are currently waiting for this function to be scheduled.
MAXQ maxq
The maximum number of Db2 agents that have waited for this function to be scheduled since the last START SPECIFIC FUNCTION command was issued for this function.
TIMEOUT timeout
The number of times that an SQL statement timed out while waiting for the function to be scheduled since the last START SPECIFIC FUNCTION command was issued for this function.

An SQL statement can time out if the function is stopped by the STOP SPECIFIC FUNCTION command with the ACTION(QUEUE) option. This specification causes requests for the function to time out after the interval that is defined by the STORTIME subsystem parameter is exceeded.

FAIL fail
The number of times that this function has abended since it was last started.
WLM_ENV wlm_env
The MVS Workload Manager environment name for this function.
ALL FUNCTIONS STARTED FOR THIS SCHEMA.
This line is displayed when both of the following conditions are true:
  • A STOP FUNCTION SPECIFIC(*.*) command operation was in effect when DISPLAY FUNCTION SPECIFIC was issued.
  • All of the functions are started for the schema that is identified in a preceding line in the output.
FUNCTIONS begin - end STOP (act)
This line is displayed when a STOP SPECIFIC FUNCTION command caused a range of functions to be stopped. This situation can occur when the command was issued with an asterisk (*) in the function name.
begin
The first function name in the range of functions that are currently stopped.
end
The last function name in the range of functions that are currently stopped.
act
The action that was specified on the STOP SPECIFIC FUNCTION command.
ALL OTHER FUNCTIONS IN OTHER SCHEMAS STOPPED act
This line is displayed when both of the following conditions are true:
  • A STOP FUNCTION SPECIFIC(*.*) command operation was in effect when the DISPLAY FUNCTION SPECIFIC command was issued.
  • Any functions that are not already listed in this DISPLAY FUNCTION SPECIFIC output are stopped.

act indicates the action that was specified on the STOP FUNCTION command.

DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
The report completed successfully.

ERROR messages for -DISPLAY FUNCTION SPECIFIC

The following messages in the DISPLAY FUNCTION SPECIFIC output indicate that an error occurred:

csect-name FUNCTION HAS NOT BEEN ACCESSED OR IS NOT DEFINED
The routine name that was supplied on the DISPLAY FUNCTION SPECIFIC command either does not exist or has not been accessed since Db2 started. The specific function name might not be in the SYSIBM.SYSROUTINES catalog table.

Processing continues for any additional routine names that were supplied on the command.

DISPLAY TERMINATED WITH MAX LINES
The DISPLAY FUNCTION SPECIFIC report was truncated. The report was generated in response to a command from an MVS console, and more than 254 messages were generated. Only 254 messages are returned.

Command processing completes. The truncated report is written to the MVS console.

Reissue the DISPLAY FUNCTION SPECIFIC command and specify a smaller number of routines. Specify a list of routines, a schema qualifier, or a partial routine name in the DISPLAY command rather than the default (*.*). Alternatively, reissue the command from the DB2 Commands panel of DB2I or from a batch job rather than from the MVS console.

DSNX994I SCOPE(GROUP) COMMAND CANNOT BE PROCESSED DUE TO COMMAND ALREADY IN PROGRESS
See DSNX994I.

Examples for -DISPLAY FUNCTION SPECIFIC

Example: Displaying information about all user-defined functions in a schema
The following command displays information about all functions in the PAYROLL schema and the HRPROD schema.
-DISPLAY FUNCTION SPECIFIC(PAYROLL.*, HRPROD.*)

The output is similar to the following output:

DSNX975I = DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-

------ SCHEMA=PAYROLL
FUNCTION        STATUS      ACTIVE   QUED   MAXQ   TIMEOUT   FAIL    WLM_ENV
PAYRFNC1        STARTED       0       0       1       0       0      WLMENV1
PAYRFNC2        STOPQUE       0       5       5       3       0      WLMENV1
PAYRFNC3        STARTED       2       0       6       0       0      WLMENV1
USERFNC4        STOPREJ       0       0       1       0       0      WLMENV3
 
------ SCHEMA=HRPROD
FUNCTION        STATUS      ACTIVE   QUED   MAXQ   TIMEOUT   FAIL    WLM_ENV
HRFNC1          STARTED       0       0       1       0       0      WLMENV2
HRFNC2          STOPREJ       0       0       1       0       0      WLMENV2
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I = DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION
Example: Displaying information about selected user-defined functions in a schema
The following command displays information about functions USERFNC2 and USERFNC4 in the PAYROLL schema.
-DISPLAY FUNCTION SPECIFIC(PAYROLL.USERFNC2,PAYROLL.USERFNC4)

The output is similar to the following output:

DSNX975I = DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-
 
------ SCHEMA=PAYROLL
FUNCTION        STATUS      ACTIVE   QUED   MAXQ   TIMEOUT   FAIL    WLM_ENV
USERFNC2        STOPQUE       0       5       5       3       0      WLMENV3
USERFNC4        STOPREJ       0       0       1       0       0      WLMENV3
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I = DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION
Example: Displaying information about stopped user-defined functions
Suppose that you issue the following commands:
-STOP FUNCTION SPECIFIC(SYSADM.FN*) ACTION(QUEUE)
-DISPLAY FUNCTION SPECIFIC(SYSADM.*)

The output looks similar to the following output:

DSNX975I = DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT FOLLOWS-
 
------ SCHEMA=SYSADM
FUNCTION       STATUS    ACTIVE   QUED  MAXQ  TIMEOUT  FAIL   WLM_ENV
FNC1           STOPQUE     0       0     0       0      0     WLMENV1
FNC2           STOPQUE     0       0     0       0      0     WLMENV3
DSNX9DIS FUNCTIONS FN - FN* STOP QUEUE
DSNX9DIS DISPLAY FUNCTION SPECIFIC REPORT COMPLETE
DSN9022I = DSNX9COM '-DISPLAY FUNC' NORMAL COMPLETION