NAME
Data::SecsPack - pack and unpack numbers in accordance with SEMI E5-94
SYNOPSIS
#####
# Subroutine interface
#
use Data::SecsPack qw(pack_int pack_num str2int unpack_num);
($format, $integers) = pack_int($format, @string_integers);
($format, $numbers, $string) = pack_num($format, @strings);
$integer = str2int($string);
($string, @integers) = str2int(@strings);
\@numbers = unpack_num($format, $string_numbers);
#####
# Class interface
#
use Data::SecsPack;
($format, $integers) = Data::Str2Num->pack_int($format, @string_integers);
($format, $numbers, $string) = Data::Str2Num->pack_num($format, @strings);
$integer = Data::Str2Num->str2int($string)
($string, @integers) = Data::Str2Num->str2int(@strings);
\@numbers = Data::Str2Num->unpack_num($format, $string_numbers); DESCRIPTION
The subroutines in the Data::SecsPack module packs and unpacks numbers in accordance with SEMI E5-94. The E5-94 establishes the standard for communication between the equipment used to fabricate semiconductors and the host computer that controls the fabrication. The equipment in a semiconductor factory (fab) or any other fab contains every conceivable known microprocessor and operating system known to man. And there are a lot of specialize real-time embedded processors and speciallize real-time embedded operating systems in addition to the those in the PC world.
The communcication between host and equipment used packed nested list data structures that include arrays of characters, integers and floats. The standard has been in place and widely used in china, germany, korea, japan, france, italy and the most remote places on this planent for decades. The basic data structure and packed data formats have not changed for decades.
This stands in direct contradiction to common conceptions of many in the Perl community. The following quote is taken from page 761, Programming Perl third edition, discussing the pack subroutine:
"Floating-point numbers are in the native machine format only. Because of the variety of floating format and lack of a standard "network" represenation, no facility for interchange has been made. This means that packed floating-point data written on one machine may not be readable on another. That is a problem even when both machines use IEEE floating-point arithmetic, because the endian-ness of memory representation is not part of the IEEE spec."
SEMI E5-94 and their precessors do standardize the endian-ness of floating point, the packing of nested data, used in many programming languages, and much, much more. The nested data has many performance advantages over the common SQL culture of viewing and representing data. The automated fabs of the world make use of nested data not only for communication between machines but also for local processing at the host and equipment.
The endian-ness of SEMI E5-94 is the first MSB byte. Maybe this is because it makes it easy to spot numbers in a packed data structure.
SECSII Format
The Data::SecsPack suroutines packs and unpacks numbers in accordance with SEMI E5-94, Semiconductor Equipment Communications Standard 2 (SECS-II), section 6 Data Structures, Figure 1, Item and List Header, and Table 1, Item Format Codes. The base copyright hard copy paper and PDF files avaiable from
Semiconductor Equipment and Materials International
805 East Middlefield Road,
Mountain View, CA 94043-4080 USA
(415) 964-5111
Easylink: 62819945
http://www.semiconductor-intl.org
http://www.reed-electronics.com/semiconductor/
Rows of SEMI E5-94 table 1, Item Format Codes, relating to numbers, with the addition of the customary unpack format code and the hex of the format code are as follows:
C<Item Format COde Table>
unpacked binary octal hex description
----------------------------------------
T 001001 11 0x24 Boolean
S8 011000 30 0x60 8-byte integer (signed)
S1 011001 31 0x62 1-byte integer (signed)
S2 011010 32 0x64 2-byte integer (signed)
S4 011100 34 0x70 4-byte integer (signed)
F4 100000 40 0x80 8-byte floating
F8 100100 44 0x90 4-byte floating
U8 101000 50 0xA0 8-byte integer (unsigned)
U1 101001 51 0xA4 1-byte integer (unsigned)
U2 101010 52 0xA8 2-byte integer (unsigned)
U4 101100 54 0xB0 4-byte integer (unsigned)Notes:
ASCII format - Non-printing characters are equipment specific
Integer formats - most significant byte sent first
floating formats - IEEE 753 with the byte containing the sign sent first.
SEMI E5-94, section 6 Data Structures, establishes the requirements for the data strutures and data items.
pack_int subroutine
($format, $integers) = pack_int($format, @string_integers);The pack_int subroutine takes an array of strings, <@string_integers>, and a format code, as specifed in the above Item Format Code Table and packs the integers, $integers in the $format in accordance with SEMI E5-94. The pack_int subroutine also accepts the format code I1 I2 I8 and format codes with out the bytes-per-element number and packs the numbers in the format using the less space, with unsigned preferred over signed. In any case, the pack_int subroutine returns the correct $format of the packed $integers.
When the pack_int encounters an error, it returns undef for $format and a description of the error as $integers. All the @string_integers must be valid Perl numbers.
pack_num subroutine
($format, $numbers, $string) = pack_num($format, @strings);Currently pack_num only supports integers. The support of floating point is under development.
The pack_num subroutine does a quick scan of @strings to see if it can find a floating point number. If the pack_num routine finds a float, it returns "floating point under development" error; otherwise, it processes @strings for integers.
The pack_num subroutine process @strings for integers in two steps. The pack_num subroutine uses str2int to convert the parse the leading numbers from the @strings as follows:
($string, @integers) = str2int(@strings); The pack_num subroutine uses pack_int to pack the @integers in accordance with SEMI E5-94 as follows:
($format, $numbers) = pack_int($format, @string_integers);The results of the integer processing is the array
C<($format, $numbers, $string)>The str2int subroutine does not report any errors while the pack_int routine and thus the pack_num routine reports errors by an undefined $format and the error message in $numbers
str2int subroutine
$integer = str2int($string);
($string, @integers) = str2int(@strings); The Data::SecsPack program module translates an scalar string to a scalar integer. Perl itself has a documented function, '0+$x', that converts a scalar to so that its internal storage is an integer (See p.351, 3rd Edition of Programming Perl). If it cannot perform the conversion, it leaves the integer 0. Surprising not all Perls, some Microsoft Perls in particular, may leave the internal storage as a scalar string.
The scalar str2int subroutine is basically the same except if it cannot perform the conversion to an integer, it returns an "undef" instead of a 0. Also, if the string is a decimal or floating point, it will return an undef. This makes it not only useful for forcing an integer conversion but also for testing a scalar to see if it is in fact an integer scalar. The scalar str2int is the same and supercedes C&<Data::Str2Num::str2int>. The Data::SecsPack program module superceds the Data::Str2Num program module.
The str2int subroutine in an array context supports converting multiple run of numbers in an array of strings @strings to an array of integers, @integers. It keeps converting the strings, starting with the first string in @strings, continuing to the next and next until it fails an conversion. The str2int returns the join of the remaining strings in @strings and the array of integers @integers.
unpack_num subroutine
\@numbers = unpack_num($format, $string_numbers); The unpack_num subroutine unpacks an array of numbers $string_numbers packed in accordance with SEMI-E5 $format. A valid $format is in accordance with the above Item Format Code Table. The floating point formats F4 F8 return the error "Floating point under development".
The unpack_num returns a reference, \@numbers, to the unpacked number array or scalar error message $error. To determine a valid return or an error, check that ref of the return exists or is 'ARRAY'.
REQUIREMENTS
Coming soon.
DEMONSTRATION
~~~~~~ Demonstration overview ~~~~~Perl code begins with the prompt
=>The selected results from executing the Perl Code follow on the next lines. For example,
=> 2 + 2
4
~~~~~~ The demonstration follows ~~~~~
=> use File::Package;
=> my $fp = 'File::Package';
=> my $uut = 'Data::SecsPack';
=> my $loaded;
=> my ($result,@result)
=> my $errors = $fp->load_package($uut, qw(pack_int pack_num str2int unpack_num))
=> $errors
''
=> $result = $uut->str2int('033')
'27'
=> $result = $uut->str2int('0xFF')
'255'
=> $result = $uut->str2int('0b1010')
'10'
=> $result = $uut->str2int('255')
'255'
=> $result = $uut->str2int('hello')
undef
=> [my ($string, @integers) = str2int('78 45 25', '512 1024', '100000 hello world')]
[
'hello world',
'78',
'45',
'25',
'512',
'1024',
'100000'
]
=> my ($format, $integers) = pack_num('I',@integers)
=> $format
'U4'
=> unpack('H*',$integers)
'0000004e0000002d000000190000020000000400000186a0'
=> ref(my $int_array = unpack_num('U4',$integers))
'ARRAY'
=> $int_array
[
78,
45,
25,
512,
1024,
100000
]
=> ($format, my $numbers, $string) = pack_num('I', '78 45 25', '512 1024', '100000 hello world')
=> $format
'U4'
=> $string
'hello world'
=> unpack('H*', $numbers)
'0000004e0000002d000000190000020000000400000186a0'QUALITY ASSURANCE
The module "t::Data::Str2Num" is the Software Test Description(STD) module for the "Data::Str2Num". module.
To generate all the test output files, run the generated test script, run the demonstration script and include it results in the "Data::Str2Num" POD, execute the following in any directory:
tmake -test_verbose -replace -run -pm=t::Data::Str2NumNote that tmake.pl must be in the execution path $ENV{PATH} and the "t" directory containing "t::Data::Str2Num" on the same level as the "lib" directory that contains the "Data::Str2Num" module.
NOTES
AUTHOR
The holder of the copyright and maintainer is
<support@SoftwareDiamonds.com>
COPYRIGHT NOTICE
Copyrighted (c) 2002 Software Diamonds
All Rights Reserved
BINDING REQUIREMENTS NOTICE
Binding requirements are indexed with the pharse 'shall[dd]' where dd is an unique number for each header section. This conforms to standard federal government practices, 490A ("3.2.3.6" in STD490A). In accordance with the License, Software Diamonds is not liable for any requirement, binding or otherwise.
LICENSE
Software Diamonds permits the redistribution and use in source and binary forms, with or without modification, provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
SOFTWARE DIAMONDS, http::www.softwarediamonds.com, PROVIDES THIS SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING USE OF THIS SOFTWARE, EVEN IF ADVISED OF NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE POSSIBILITY OF SUCH DAMAGE.
SEE_ALSO: