Command Functions of PurePerl MySQL API
Developing a PurePerl MySQL API – Part 5
Writing a Perl Module
Foreword: In this part of the series I develop the command functions of PurePerl MySQL API.
By: Chrysanthus Date Published: 28 Jan 2015
Introduction
The Task and function Names
A number of tasks have to be carried out with the command packet. Each task has a corresponding function. The following is a list of the tasks and the function names given:
- Tell the server to change the default database for the session to the one specified by the argument – Decimal code, 2 – Argument: database name. The function name will be, select_db().
- Tell the server to run the query – Decimal code, 3 – Argument: query string without semicolon. The function name will be query();
- Tell the server to shut down – Decimal code, 8 – Argument: No argument. The function name will be, shutdown().
- Tell the server to send back a string containing a brief status report - Decimal code, 9 – Argument: No argument. The function will be called, status().
- Tell the server to respond with an OK packet. If the server is alive and reachable, it will - Decimal code, 14 – Argument: No argument. The function will be called, ping().
The code of these functions is in the Mysql module (Mysql.pm). For the rest of this article, I give you the code of some of the functions and their explanations. The rest of the functions will be explained later in this series; however, I mention them here.
Function Details
The syntax for the select_db() function is:
Boolean select_db(databaseName)
The function takes as argument, the database name of the new database. It returns 1 on success and 0 on failure. On failure, the error is assigned to the variable, $Error_msg in the Mysql package.
The code is:
sub select_db
{
my $db_pkt = Command::command(2, $_[0]);
#send the DB packet
send (SOCK, $db_pkt, 0);
#receive the reply
my $db_reply;
recv (SOCK, $db_reply, 200, 0);
#determine and return 1 or 0
my ($dummy0,$OKHex) = unpack("H8H2", $db_reply);
if ($OKHex eq "ff")
{
my %ha = Error::error($db_reply);
$Error_msg .= $ha{'error_msg'};
return 0;
}
if ($OKHex eq "00")
{
my %ha = OK::ok($db_reply);
$Message = $ha{'OK_msg'};
return 1;
}
}
The function calls the command() function in the command packet. A command packet is returned. It is the command package that produces this packet, and not the server. The packet should have the database name in one of its byte sequences. The packet is sent to the server. The reply is received; it is either an OK packet or an error packet. If it is an error packet, zero is returned by the function and an error message is assigned to the $Error_msg variable. If it is an OK packet then 1 is returned by the function.
I will talk about this function later in this series.
The shutdown() Function
I will talk about this function later in this series.
The status() Function
The syntax for the status() function is:
Boolean status()
The function takes no argument. It returns 1 on success and 0 on failure. On failure, the error is assigned to the variable, $Error_msg in the Mysql package. On success the report (string) is assigned to the variable, $Message in the Mysql package.
The code is:
sub status
{
my $db_pkt = Command::command(9);
#send the DB packet
send (SOCK, $db_pkt, 0);
#receive the reply
my $db_reply;
recv (SOCK, $db_reply, 200, 0);
#determine and return 1 or 0 with result or error
my ($dummy,$report) = unpack("A4A*", $db_reply);
my ($dummy,$OKByt) = unpack("A4A", $db_reply);
my $zero_byte = pack('H2', "00");
my $OKByt_16 = $zero_byte . $OKByt;
my $OKByt_16_D = unpack('S>', $OKByt_16);
if ($OKByt_16_D == 255)
{
my %ha = Error::error($db_reply);
$Error_msg .= $ha{'error_code'} . ": " . $ha{'error_msg'};
return 0;
}
else
{
$Message = $report;
return 1;
}
}
The explanation is similar to that of the select_db() function. If the return value is zero, the error message is assigned to the $Error_msg variable in the Mysql.pm file; otherwise the report is assigned to the $Message variable in the same file. All variables in the API, accessible by your script (program) are in the Mysql.pm file.
The syntax for the ping() function is:
Boolean ping()
The function takes no argument. It returns 1 on success and 0 on failure. On failure, the error is assigned to the variable, $Error_msg in the Mysql package.
The code is:
sub ping
{
my $db_pkt = Command::command(14);
#send the DB packet
send (SOCK, $db_pkt, 0);
#receive the reply
my $db_reply;
recv (SOCK, $db_reply, 200, 0);
#determine and return 1 or 0
my ($dummy,$OKByt) = unpack("H8H2", $db_reply);
my $OKByt_16_D = hex($OKByt);
if ($OKByt_16_D == 255)
{
my %ha = Error::error($db_reply);
$Error_msg .= $ha{'error_msg'};
return 0;
}
elsif ($OKByt_16_D == 0)
{
return 1;
}
else
{
return 0;
}
}
The explanation is similar to that of the select_db() function, but the return code segment is a bit different.
That is it for this part of the series. In the next part of the series we shall look at the OK and Error packets.
Chrys
Related Links
Internet Sockets and PerlPerl pack and unpack Functions
Writing MySQL Protocol Packets in PurePerl
Developing a PurePerl MySQL API
Using the PurePerl MySQL API
More Related Links
Perl Mailsend
PurePerl MySQL API
Perl Course - Professional and Advanced
Major in Website Design
Web Development Course
Producing a Pure Perl Library
MySQL Course
BACK NEXT