Submit a Request to the Junos XML Protocol Server in Perl Client Applications
In a Junos XML Protocol Perl client application, after establishing a connection to a Junos XML protocol server, the client application can submit one or more requests by invoking the Perl methods that are supported in the version of the Junos XML protocol and Junos XML API used by the application.
Each version of software supports a set of methods that correspond to CLI operational mode commands. For a list of the operational methods supported in the current version, see Mapping Junos OS Commands to Perl Methods and the files stored in the lib/JUNOS/release directory of the Junos XML protocol Perl distribution (release is the Junos OS version code, such as 20.4R1 for the initial version of Junos OS Release 20.4). The files have names in the format package_methods.pl, where package is a software package.
The set of methods that correspond to operations on configuration objects is defined in the lib/JUNOS/Methods.pm file in the Junos XML protocol Perl distribution.
See the following sections for more information:
Providing Method Options or Attributes
Many Perl methods have one or more options or attributes. The following list describes the notation used to define a method’s options in the lib/JUNOS/Methods.pm and lib/JUNOS/release/package_methods.pl files, and the notation that an application uses when invoking the method:
A method without options is defined as
$NO_ARGS
, as in the following entry for theget_system_uptime_information
method:## Method : <get-system-uptime-information> ## Returns: <system-uptime-information> ## Command: "show system uptime" get_system_uptime_information => $NO_ARGS,
To invoke a method without options, follow the method name with an empty set of parentheses as in the following example:
$jnx->get_system_uptime_information( );
A fixed-form option is defined as type
$TOGGLE
. In the following example, theget_software_information
method takes two fixed-form options,brief
anddetail
:## Method : <get-software-information> ## Returns: <software-information> ## Command: "show version" get_software_information => brief => $TOGGLE, detail => $TOGGLE, },
To include a fixed-form option when invoking a method, set it to the value
1
(one) as in the following example:$jnx->get_software_information(brief => 1);
An option with a variable value is defined as type
$STRING
. In the following example, theget_cos_drop_profile_information
method takes theprofile_name
argument:## Method : <get-cos-drop-profile-information> ## Returns: <cos-drop-profile-information> ## Command: "show class-of-service drop-profile" get_cos_drop_profile_information => { profile_name => $STRING, },
To include a variable value when invoking a method, enclose the value in single quotes as in the following example:
$jnx->get_cos_drop_profile_information(profile_name => 'user-drop-profile');
An attribute is defined as type
$ATTRIBUTE
. In the following example, theload_configuration
method takes therollback
attribute:load_configuration => { rollback => $ATTRIBUTE },
To include a numerical attribute value when invoking a method, set it to the appropriate value. The following example rolls the candidate configuration back to the previous configuration that has an index of 2:
$jnx->load_configuration(rollback => 2);
To include a string attribute value when invoking a method, enclose the value in single quotes as in the following example:
$jnx->get_configuration(format => 'text');
A set of configuration statements or corresponding tag elements is defined as type
$DOM
. In the following example, theget_configuration
method takes a set of configuration statements (along with two attributes):get_configuration => { configuration => $DOM, format => $ATTRIBUTE, database => $ATTRIBUTE, },
To include a set of configuration statements when invoking a method, provide a parsed set of statements or tag elements. The following example refers to a set of Junos XML configuration tag elements in the config-input.xml file. For a more detailed discussion about modifying the configuration, see Example: Changing the Configuration Using Junos XML Protocol Perl Client Applications.
my $parser = new XML::DOM::Parser; $jnx->load_configuration( format => 'xml', action => 'merge', configuration => $parser->parsefile(config-input.xml) );
A method can have a combination of fixed-form options,
options with variable values, attributes, and a set of configuration
statements. For example, the get_forwarding_table_information
method has four fixed-form options and five options with variable
values:
## Method : <get-forwarding-table-information> ## Returns: <forwarding-table-information> ## Command: "show route forwarding-table" get_forwarding_table_information => { detail => $TOGGLE, extensive => $TOGGLE, multicast => $TOGGLE, family => $STRING, vpn => $STRING, summary => $TOGGLE, matching => $STRING, destination => $STRING, label => $STRING, },
Submitting a Request
The following code is the recommended way to send a request
to the Junos XML protocol server and shows how to handle error conditions.
The $jnx
variable is defined to be a JUNOS::Device
object, as discussed in Connecting to the Junos XML Protocol Server Using
Perl Client Applications. A detailed discussion of the
functional subsections follows the complete code sample.
my %arguments = ( ); %arguments = ( argument1 => value1 , argument2 => value2 , ...); argument3 => value3 , ...); my $res = $jnx-> method (%args); unless ( ref $res ) { $jnx->request_end_session( ); $jnx->disconnect( ); print "ERROR: Could not send request to $hostname\n"; } my $err = $res->getFirstError( ); if ($err) { $jnx->request_end_session( ); $jnx->disconnect(); print "ERROR: Error for $hostname: " . $err->{message} . "\n"; }
The first subsection of the preceding code sample creates
a hash called %arguments
to define values
for a method’s options or attributes. For each argument, the
application uses the notation described in Providing Method Options or Attributes.
my %arguments = ( ); %arguments = ( argument1 => value1 , argument2 => value2 , ...); argument3 => value3 , ...);
The application then invokes the method, defining the $res
variable to point to the JUNOS::Response
object that the Junos XML protocol server returns in response to
the request (the object is defined in the lib/JUNOS/Response.pm file in the Junos XML protocol Perl distribution):
my $res = $jnx-> method (%args);
If the attempt to send the request failed, the application prints an error message and closes the connection:
unless ( ref $res ) { $jnx->request_end_session(); $jnx->disconnect(); print "ERROR: Could not send request to $hostname\n"; }
If there was an error in the Junos XML protocol server’s
response, the application prints an error message and closes the connection.
The getFirstError
function is defined in
the JUNOS::Response
module (lib/JUNOS/Response.pm) in the Junos XML protocol
Perl distribution.
my $err = $res->getFirstError( ); if ($err) { $jnx->request_end_session( ); $jnx->disconnect( ); print "ERROR: Error for $hostname: " . $err->{message} . "\n"; }