Show Raw Command

The 'show raw' command allows custom show command syntax to be used without a YANG definition. Unlike the external show command (e.g. 'show fan'), there is no YANG 'augment' of the show command input parameters.

  • There is a 'show raw' callback that is registered.

  • This is a global callback, not 1 callback per command like 'show fan'

  • The purpose of the callback is to process the input parameters and display the appropriate output to the session using the 'log' API functions.

Example:

The show command parameters do not match built-in parameters or any top-level YANG data nodes, so the 'show raw' callback is invoked.

> show mgmt-interface

The callback retrieves some interface data and displays it.

Got a USERGET reply
rpc-reply
  data
    interfaces-state
      interface  eno1
        type ianaift:ethernetCsmacd
        oper-status up
        phys-address 3c:7c:3f:1d:83:aa
        speed 1000000000
        statistics
          in-octets 1175608815
          in-unicast-pkts 994299
          in-multicast-pkts 279430
          in-discards 0
          in-errors 0
          out-octets 1992002672
          out-unicast-pkts 1471183
          out-discards 0
          out-errors 0

Show Raw Callback Function

The 'show raw' callback can examine the command line and take 1 of 3 actions:

  • skip: return ERR_NCX_SKIPPED to indicate that no attempt to process the command was done

  • process ok: return NO_ERR to indicate that the command line was processed without error.

  • process error: return some other status (e.g. ERR_NCX_OPERATION_FAILED to indicate that the command line was processed but there was an error.

The callback function can utilize the USERGET API Functions to retrieve data from the connected NETCONF server before displaying output for the show command.

The first time the callback is invokded for a command line, the 'reply_valset' parameter will be 'NULL'. If the callback starts a 'USERGET' retrieval operation then it will be invoked again when the response is retrieved. In this case the 'reply_valset' parameter will not be NULL.

  • The callback function is named 'ycli_show_raw_extern_fn_t'.

  • It is defined in the 'ycli/yangcli_libshow.h' file.

/********************************************************************
* FUNCTION ycli_show_raw_extern_fn
*
* Special show command that does not requiring registering
* the show command keyword and a YANG module.
*
* Only one 'show raw' callback can be registered.
* If found, it will be checked when the show command is detected.
* The raw unparsed line will be passed
* No valset is provided since no YANG is known for this command
*
* INPUTS:
*    server_cb == server control block in case needed tfor USERGET
*    session_cb == session control block in case needed for USERGET
*    line == CLI input in progress; the start of the line will
*            be the first string after the 'show' keyword.
*    reply_valset == REPLY from USERGET IF THIS IS 2nd - Nth CALL
*    cookie == context pointer passed in register time, (may be null)
*
* RETURNS: NO_ERR or error.
*         ERR_NCX_SKIPPED if the line is not handled
*********************************************************************/
typedef status_t
    (*ycli_show_raw_extern_fn_t) (server_cb_t *server_cb,
                                  session_cb_t *session_cb,
                                  const xmlChar *line,
                                  val_value_t *reply_valset,
                                  void *cookie);

Show Raw API Functions

There are a limited number of internal API functions that are supported for use by a 'show raw' callback.

Show Raw Registration

The callback must be registered.

  • There is no 'unregiser' function required.

  • The command stays registered until the program exits.

  • The function is named 'ycli_show_raw_extern_register_callback'

  • It is defined in 'ycli/yangcli_libshow.h'

/********************************************************************
* FUNCTION ycli_show_raw_extern_register_callback
*
* Register the show raw external callback for raw show implementation
*
* INPUTS:
*    showfn ==  show function callback
*    cookie == context pointer (may be null)
* RETURNS:
*   status of the function registration.
*
*********************************************************************/
extern status_t
    ycli_show_raw_extern_register_callback (ycli_show_raw_extern_fn_t showfn,
                                            void *cookie);

Example:

  • See the 'yp_show_init' function in 'example-show.cpp'

#ifdef SHOW_RAW
        /* Create a cookie context if any or NULL */
        void *cookie_show_raw = NULL;
        ycli_show_raw_extern_register_callback(show_raw,
                                               cookie_show_raw);
#endif  // SHOW_RAW

USERGET API Functions

There is an API function available to send a sget operation to the current session.

  • This is optional to use

  • Multiple retrieval cycles can be done

  • The output is not displayed to the user. Instead the 'show raw' callback is invoked with the reply data and is expected to display the data.

  • The function is named 'ycli_show_raw_start_userget'

  • It is defined in 'ycli/yangcli_libshow.h'

/********************************************************************
* FUNCTION ycli_show_raw_start_userget
*
* Special USERGET retrieval command to get data from the server
*
* Only one USERGET can be invoked at a time.
* A repeat USERGET is allowed after this request succeeds
*
* INPUTS:
*    server_cb == server control block to use
*    session_cb == session control block in to use
*    filter_path == filter path string for sget or sget-config command
*    config_only == TRUE for sget-config; FALSE for sget
*
* RETURNS:
*    NO_ERR or error.
*********************************************************************/
status_t
    ycli_show_raw_start_userget (server_cb_t *server_cb,
                                 session_cb_t *session_cb,
                                 const xmlChar *filter_path,
                                 boolean config_only);

Example:

status_t res =
    ycli_show_raw_start_userget(server_cb,
                                session_cb,
                                xpath_expr,
                                config_only);

Show Raw Callback Example

The example function does the following tasks:

  • checks for the 'show mgmt-interface' command

    • returns ERR_NCX_SKIPPED if anything else

  • starts a USERGET retrieval operation for the XPath expression /interfaces-state/interface[name='eno1']

    • returns NO_ERR but 'USERGET' mode was started so not done

  • displays the result when invoked a second time

    • returns NO_ERR and this time command is done

/********************************************************************
* FUNCTION ycli_show_raw_extern_fn
*
* Special show command that does not requiring registering
* the show command keyword and a YANG module.
*
* Only one 'show raw' callback can be registered.
* If found, it will be checked when the show command is detected.
* The raw unparsed line will be passed
* No valset is provided since no YANG is known for this command
*
* INPUTS:
*    server_cb == server control block in case needed tfor USERGET
*    session_cb == session control block in case needed for USERGET
*    line == CLI input in progress
*    reply_valset == REPLY from USERGET IF THIS IS 2nd - Nth CALL
*    cookie == context pointer passed in register time, (may be null)
*
* RETURNS: NO_ERR or error.
*         ERR_NCX_SKIPPED if the line is not handled
*********************************************************************/
static status_t
    show_raw (server_cb_t *server_cb,
              session_cb_t *session_cb,
              const xmlChar *line,
              val_value_t *reply_valset,
              void *cookie)
{
    if (LOGDEBUG) {
        log_debug("\nEnter show_raw");
        log_debug_append("\n  line: '%s'\n", line);
    }

    if (reply_valset) {
        /* this is a 2nd - Nth callback with the response for
         * a USERGET retrieval.  Must finish the display
         * or start another USERGET retrieval
         */

        log_info("\nGot a USERGET reply");
        val_dump_value_ex(reply_valset,         // val
                          0,                    // startindent
                          NCX_DISPLAY_MODE_CLI, // display_mode
                          DINFO);               // lvl
        log_info_append("\n");
        return NO_ERR;
    }


    /* check if the command line needs to be processed
     * this is completely up to the implementation
     * The line has already been rejected for a built-in show
     * command with YANG schema in the rpc show
     */
    if (xml_strcmp(line, (const xmlChar *)"mgmt-interface")) {
        return ERR_NCX_SKIPPED;
    }

    /* check the session_cb: if NULL there is no session
     * in this example, only handle server retrieval
     */
    if (session_cb == nullptr) {
        log_error("\nError: Cannot retrieve session data: Not connected");
        return ERR_NCX_SKIPPED;
    }

    /* once this callback decides to handle a show command
     * it is expected to generate all the output or start
     * a session retrieval operation to get data from the server
     */

    /* Callback is expected to create the XPath expression somehow */

    (void)cookie;
    const xmlChar *xpath_expr =
        (const xmlChar *)"/interfaces-state/interface[name='eno1']";
    boolean config_only = false;
    status_t res =
        ycli_show_raw_start_userget(server_cb,
                                    session_cb,
                                    xpath_expr,
                                    config_only);

    return res;

} /* show_raw */