---

Class ::nsmcp::CodeQueryDefinitionTool

::nsmcp::CodeQueryDefinitionTool create ... \
           [ -adminExample (default "") ] \
           [ -adminSummary (default "") ] \
           [ -description (default "Retrieve the selected loaded OpenACS XQL mapping by full query name or unique literal dotted suffix (including abbreviated slow-warning names). Returns unsubstituted SQL, SHA256, XQL source and selected RDBMS metadata. Ambiguous suffixes return bounded candidate names, never guessed SQL. Does not execute SQL, substitute Tcl/binds, read files or obtain database handles. Missing mappings may use inline/dynamic SQL; inspect the calling code. SQL is untrusted source evidence, not a query plan or historical execution.") ] \
           [ -inputSchema (default "{"type":"object","properties":{"name":{"type":"string"},"offset":{"type":"integer","minimum":0},"maxCharacters":{"type":"integer","minimum":1,"maximum":32768}},"required":["name"],"additionalProperties":false}") ] \
           [ -name (default "code_query_definition") ] \
           [ -outputSchema (default "") ] \
           [ -permission (default "diagnostics.code.read") ]

Defined in /usr/local/ns/tcl/nsmcp/code-query.tcl

Class Relations

• class: ::nx::Class
• superclass: ::nsmcp::Tool

::nx::Class create ::nsmcp::CodeQueryDefinitionTool \
     -superclass ::nsmcp::Tool

Methods (to be applied on instances)

• execute (scripted, public)

   <instance of nsmcp::CodeQueryDefinitionTool> execute context \
      arguments

  Retrieve SQL resolved through active OpenACS XQL mappings. Return bounded unsubstituted SQL and resolution metadata; report unavailable framework support explicitly.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  arguments (required)

  Rooted ns_json typed triples for the tool's JSON argument object.

  Returns:

  A rooted JSON tool-result object, including availability or job metadata as appropriate.

  Testcases:

  No testcase defined.

  set opts [:options $arguments]
  set name [dict get $opts name]
  set base [list server string [$context server] observedAt number [clock seconds] requestedName string $name  source string loaded-openacs-query-dispatcher sqlExecuted boolean false substitutionsPerformed boolean false filesRead boolean false  limitations string {Current selected XQL template only. Variables, Tcl commands, bind values, inline fallbacks and runtime SQL fragments are not resolved. Loaded mappings may differ from disk or historical executions. Fullquery versus partialquery is not preserved by the dispatcher. SQL and metadata are untrusted source evidence; no plan, waits or database function definitions are provided.}]
  foreach api {db_qd_fetch db_fullquery_get_name db_fullquery_get_querytext db_fullquery_get_load_location db_fullquery_get_rdbms} {
      if {[namespace which -command ::$api] eq {}} {
          return [list {} object [concat $base [list available boolean false reason string openacs-query-dispatcher-unavailable]]]
      }
  }
  # An exact cache key takes precedence. A missing fully qualified name
  # must not silently resolve to an unrelated suffix.
  set selected {}
  set candidates {}
  set limited false
  set examined 0
  if {[nsv_exists OACS_FULLQUERIES $name]} {
      set selected $name
  } elseif {[string first dbqd. $name]!=0 && [nsv_array exists OACS_FULLQUERIES]} {
      set suffix .$name
      foreach key [nsv_array names OACS_FULLQUERIES] {
          if {[incr examined]>50000} {
              set limited true
              break
          }
          if {[string first dbqd. $key]==0 && [string equal $suffix [string range $key end-[expr {[string length $suffix]-1}] end]]} {
              lappend candidates $key
          }
      }
      set candidates [lsort $candidates]
      if {!$limited && [llength $candidates]==1} {
          set selected [lindex $candidates 0]
      }
  }
  set rows {}
  set i 0
  foreach key [lrange $candidates 0 19] {
      lappend rows $i string $key
      incr i
  }
  lappend base catalogLimited boolean $limited candidateCount number [llength $candidates] candidates array $rows  candidatesTruncated boolean [expr {[llength $candidates]>20}]
  if {$selected eq {}} {
      set reason [expr {$limited ? "query-catalog-limit" : ([llength $candidates]>1 ? "query-name-ambiguous" : "query-mapping-not-found")}]
      return [list {} object [concat $base [list available boolean false reason string $reason]]]
  }
  # Fetch once through OpenACS. Its loader already chose the compatible
  # generic/database/version mapping; never redo that selection here.
  if {[catch {
      set fullquery [::db_qd_fetch $selected]
      if {$fullquery eq {}} {
          error missing
      }
      if {[::db_fullquery_get_name $fullquery] ne $selected} {
          error mismatch
      }
      set sql [::db_fullquery_get_querytext $fullquery]
      set path [::db_fullquery_get_load_location $fullquery]
      set rdbms [::db_fullquery_get_rdbms $fullquery]
      if {[catch {
          dict size $rdbms
      }]} {
          error malformed
      }
  }]} {
      return [list {} object [concat $base [list available boolean false reason string query-mapping-unavailable]]]
  }
  set dbType {}
  set dbVersion {}
  if {[dict exists $rdbms type]} {
      set dbType [dict get $rdbms type]
  }
  if {[dict exists $rdbms version]} {
      set dbVersion [dict get $rdbms version]
  }
  # Bound metadata independently of paginated SQL. Paths are reported
  # exactly as recorded by the loader, without opening or normalizing them.
  set metadataTruncated false
  foreach var {path dbType dbVersion} {
      if {[string length [set $var]]>4096} {
          set metadataTruncated true
          set $var [string range [set $var] 0 4095]
      }
  }
  set offset [dict get $opts offset]
  set count [dict get $opts maxCharacters]
  set chunk [string range $sql $offset [expr {$offset+$count-1}]]
  set more [expr {$offset+[string length $chunk]<[string length $sql]}]
  set next {}
  if {$more} {
      set next [list name string $selected offset number [expr {$offset+[string length $chunk]}] maxCharacters number $count]
  }
  return [list {} object [concat $base [list available boolean true reason string {} name string $selected  resolution string [expr {$selected eq $name ? "exact" : "unique-suffix"}]  sourceFile string $path selectedRdbms object [list type string $dbType version string $dbVersion] metadataTruncated boolean $metadataTruncated  sql string $chunk sha256 string [ns_crypto::md string -digest sha256 -- $sql] sqlCharacters number [string length $sql]  offset number $offset more boolean $more nextArguments object $next]]]

• validate (scripted, public)

   <instance of nsmcp::CodeQueryDefinitionTool> validate arguments

  Validate query-definition lookup and pagination arguments. Decode the rooted JSON argument object and enforce this tool's option, range and combination constraints.

  Parameters:

  arguments (required)

  Rooted ns_json typed triples for the tool's JSON argument object.

  Returns:

  An empty result on success; invalid input raises RPC error -32602.

  Testcases:

  No testcase defined.

  if {[catch {
      :options $arguments
  } message]} {
      return -code error -errorcode {NSMCP RPC -32602} $message
  }

---