%SYS.AppMetadataStack.SQL

hidden class %SYS.AppMetadataStack.SQL extends %Library.SystemBase

The %SYS.AppMetadataStack.SQL class defines the interface for processing and retrieving information from the Application Metadata Stack (AMS) for the SQL application (ApplicationID="%SQL" [WHERE "%SQL"=$$$AMSApplicationIDSQL]).

The GetStackInfo() method within this class returns a snapshot of the SQL Query information that is stored on the Application Metadata Stack (AMS), and this information is used by the INFORMATION.SCHEMA.CURRENTSTATEMENTS class for its data ResultSet.

The Application Metadata Stack (AMS), which is kept in shared memory, allows applications to push metadata information on the stack to define what task is being performed by the process at any given time. Information from the stack is automatically discarded when the process leaves the current frame (descending the frame stack). This information can be inspected and consumed by monitoring and profiling tools, such as ^%SS & the SMP, and reported to a user upon request.

The Application Metadata Stack (AMS) is populated with a $LIST(...) string of metadata information. The elements of this metadata string, along with the position of where each element's data is stored, can be found by inspecting the positional MACROs defined within the %msql.INC file under the section entitled APPLICATION METADATA STACK (AMS) MACROs

The first element of this metadata string is the AppMetadataStackID which itself is a $LIST(...) string that is comprised of two or more elements that can be used to uniquely identify each metadata string on the Application Metadata Stack (AMS). The first element of the AppMetadataStackID string is always the ApplicationID which identifies the application that pushed this metadata information onto the Application Metadata Stack (AMS) for future processing. The ApplicationID has the following values:

ApplicationID	Application Name	Description
"%SQL" ::= $$$AMSApplicationIDSQL	SQL	All SQL Interfaces: Embedded \| Dynamic \| xDBC SQL generated code and related infrastructure (such as WQM and SQM) will leverage this feature to track relevant SQL metadata, such as the statement being executed and identifiers for a "parent" query in parallelized or sharded cases.

The second element of the AppMetadataStackID string, and optionally all additional elements, is application dependent. In the case of this class %SYS.AppMetadataStack.SQL, which defines the interface for processing and retrieving information from the Application Metadata Stack (AMS) for the SQL application (ApplicationID="%SQL"), the AppMetadataStackID will be comprised of the following elements:

AppMetadataStackID ::= $LIST({ApplicationID},{SQLStatementID})

Method Inventory

GetStackInfo()

Methods

classmethod GetStackInfo(pidList As %String = "", infoOnly As %Boolean = 0, Output amsInfo, skipShardWorkMgr As %Boolean = 0, Output amsDebugID="", getAllAMS As %Boolean = 0) as %Status

The GetStackInfo() method returns an array of SQL Query information that is stored on the Application Metadata Stack (AMS). The output array amsInfo(...) returned by this method can be further refined by either or both of the input parameters pidList and/or infoOnly. The output array amsInfo(...) is used by the INFORMATION.SCHEMA.CURRENTSTATEMENTS class for its data ResultSet.

Parameters:

pidList

A $LIST(...) or comma-delimited string of PIDs to refine the output parameter array amsInfo(...), such that only the specified PIDs will be returned in the amsInfo(...) array

infoOnly

A flag to determine what is populated and returned in the output parameter array amsInfo(...):

0 - Populate and return all information nodes of the amsInfo(...) array
1 - Populate and return only the "info" node of the amsInfo(...) array

amsInfo

An output parameter which return a snapshot of the SQL Query information that is stored on the Application Metadata Stack (AMS) at the time of this method's invocation. This output array is returned with the following informational nodes:

       
           Inline-Processing Information
            
           amsInfo(<server>,pid,sqlIndexHash,"info")=<ams info list>
           Master Map: Data
         
           Index Maps
         
           amsInfo(<server>,pid,sqlIndexHash,"parent")=<parent list>
           Only defined for Child Queries
         
           amsInfo(<server>,pid,sqlIndexHash,"childStmts")=<children list>
           Only defined for Parent Queries
         
           amsInfo("orderStmts")=<order list>
           Ordered $LIST($LB(Stand-Alone/Parent/Children-Info),...)
         
           Post-Processing Information
            
           $LIST(<ams info list>,$$$AMSSQLPPStatementOrderPos)=<Statement Order>
           Position within <order list>
         
           $LIST(<ams info list>,$$$AMSSQLPPStatsListPos)=<stats list>
            
       Details
       
           <server> ::=
           $LG($LG(<ams info list>,$$$AMSSQLServerInfoListPos),2)
           $ZU(110)_":"_$g(^%SYS("SSPort"))
         
           <ams list> ::=
           $SYSTEM.Process.GetAppFrameInfo(pid)
           For $LIST(...) details, see 'InitAMSInfo^%qaqcasl.MAC'
         
           <ams info list> ::=
           $LG(<ams list>,pos)
           All pieces of the <ams list>
         
           <stats list> ::=
           $LIST(...) Pieces:
             
                 1)
                 workerCnt
                 Number of workers currently active on behalf of this SQL Statement
               
                 2)
                 startTS
                 Local timestamp in $ZDT(tsH,3,1,3) format when the SQL Query started running
               
                 3)
                 elapsedTime
                 Elapsed time of this running SQL Query in seconds (to 3 decimal points)
               
                 4)
                 startTSUTC
                 UTC timestamp in $ZDT(tsH,3,1,3) format when the SQL Query started running
               
                 NOTE: These pieces are elements of the positional MACRO $$$AMSSQLPPStatsListPos, each having its own SubPos
               
                 NOTE: Pieces 2, 3 and 4 are based on the following value: $LG(amsInfoList,$$$AMSSQLExecutionTSPos)
               
           <parent list> ::=
           $LIST(...) Pieces:
             
                 1)
                 pServer
                 Parent's Host Information
               
                 2)
                 pPID
                 Parent's PID
               
                 3)
                 pSQLIndexHash
                 Parent's SQL Index Hash
               
                 4)
                 cQueryRunType
                 Child's Query Type: { Parallel | Sharded }
               
           <children list> ::=
           $LIST(...) of SQLIndexHash for all Children Queries
         
           <order list> ::=
           $LIST(...) of $LIST(...) Pieces:
             
                 1)
                 {SA|P|CP|C}
                 {SA = Stand-Alone | P = Parent | CP = Child & Parent | C = Child} SQL Statement
               
                 2)
                 server
                 SQL Statement Host Information
               
                 3)
                 pid
                 SQL Statement PID
               
                 4)
                 sqlIndexHash
                 SQL Statement Index Hash
               
NOTE: This $LIST(...) is ordered by all Stand-Alone SQL Statements, followed by each Parent SQL Statements and its Children SQL Statements: 

                   $LIST({SA1}[,{SA2},...,{SAn}],{P1},{C1:1},...,{C1:n},[,{P2},{C2:1},...,{C2:n},...,{Pn},{Cn:1},...,{Cn:n}])

skipShardWorkMgr

A flag to determine whether to skip processing the Application Metadata Stack (AMS) for Information via the ShardWorkMgr:

0 - Process the Application Metadata Stack (AMS) for Information via the ShardWorkMgr (If one exists)
1 - Skip processing the Application Metadata Stack (AMS) for Information via the ShardWorkMgr

NOTE: This parameter is for InterSystems INTERNAL USE ONLY!
This parameter is used primarily for debugging purposes in order to run this method interactively in the foreground.

amsDebugID

An output parameter which returns the amsDebugID node within the SQL Application Metadata Stack - Debugging Tool (AMS-DT) global if the AMS-DT is enabled; Otherwise, returns the empty string ("") which indicates that no debugging information was collected

NOTE: This parameter is for InterSystems INTERNAL USE ONLY!

getAllAMS

A flag to determine if all AMS information should be collected for special internal purposes

NOTE: This parameter is for InterSystems INTERNAL USE ONLY!

Example:

The following is an example of retrieving all of the SQL Query information that is stored on the Application Metadata Stack (AMS) into the amsInfo(...) array:

     set tSC=##class(%SYS.AppMetadataStack.SQL).GetStackInfo(,,.amsInfo)

%SYS.AppMetadataStack.SQL

Method Inventory

Methods

Inherited Members

Inherited Methods

Inline-Processing Information
amsInfo(<server>,pid,sqlIndexHash,"info")=<ams info list>	Master Map: Data
	Index Maps
amsInfo(<server>,pid,sqlIndexHash,"parent")=<parent list>	Only defined for Child Queries
amsInfo(<server>,pid,sqlIndexHash,"childStmts")=<children list>	Only defined for Parent Queries
amsInfo("orderStmts")=<order list>	Ordered $LIST($LB(Stand-Alone/Parent/Children-Info),...)
Post-Processing Information
$LIST(<ams info list>,$$$AMSSQLPPStatementOrderPos)=<Statement Order>	Position within <order list>
$LIST(<ams info list>,$$$AMSSQLPPStatsListPos)=<stats list>