NAME Data::Secs2 - pack, unpack, format, transform from Perl data SEMI E5-94 nested data. SYNOPSIS ##### # Subroutine interface # use Data::Secs2 qw(); \@array = arrayify( $ref ); $body = secs_elementify($format, @cells); $body = secs_elementify($format, @cells, [@options]); $body = secs_elementify($format, @cells, {optioins}); \@secs_obj = listify(@vars); \@secs_obj = neuterify($binary_secs); \@secs_obj = neuterify($binary_secs, @options); \@secs_obj = neuterify($binary_secs, [@options]); \@secs_obj = neuterify($binary_secs, {@options}); $error = numberify( \@secs_obj ); @vars = perlify(\@secs_obj); $ref = perl_typify(\@array); $ascii_secs = secsify( \@secs_obj); $ascii_secs = secsify( \@secs_obj, @options); $ascii_secs = secsify( \@secs_obj, [@options]); $ascii_secs = secsify( \@secs_obj, {@options}); $binary_secs = secsify( \@secs_obj, type => 'binary'); $binary_secs = secsify( \@secs_obj, type => 'binary', @options); $binary_secs = secsify( \@secs_obj, [type => 'binary',@options]); $binary_secs = secsify( \@secs_obj, {type => 'binary',@options}); $string = stringify( @arg ); \@secs_obj = transify($acsii_secs); \@secs_obj = transify($acsii_secs, @options); \@secs_obj = transify($acsii_secs, [@options]); \@secs_obj = transify($acsii_secs, {@options}); $error = textify( \@secs_obj ); ##### # Class interface # use Data::Secs2; \@array = Data::Secs2->arrayify( $ref ); $body = Data::Secs2->secs_elementify($format, @cells); $body = Data::Secs2->secs_elementify($format, @cells, [@options]); $body = Data::Secs2->secs_elementify($format, @cells, {optioins}); \@secs_obj = Data::Secs2->listify(@vars); \@secs_obj = Data::Secs2->neuterify($binary_secs); \@secs_obj = Data::Secs2->neuterify($binary_secs, @options); \@secs_obj = Data::Secs2->neuterify($binary_secs, [@options]); \@secs_obj = Data::Secs2->neuterify($binary_secs, {@options}); $error = Data::Secs2->numberify( \@secs_obj ); @vars = Data::Secs2->perlify(\@secs_obj); $ref = Data::Secs2->perl_typify(\@array); $ascii_secs = Data::Secs2->secsify( \@secs_obj); $ascii_secs = Data::Secs2->secsify( \@secs_obj, @options); $ascii_secs = Data::Secs2->secsify( \@secs_obj, [@options]); $ascii_secs = Data::Secs2->secsify( \@secs_obj, {@options}); $binary_secs = Data::Secs2->secsify( \@secs_obj, type => 'binary'); $binary_secs = Data::Secs2->secsify( \@secs_obj, type => 'binary', @options); $binary_secs = Data::Secs2->secsify( \@secs_obj, [type => 'binary',@options]); $binary_secs = Data::Secs2->secsify( \@secs_obj, {type => 'binary',@options}); $body = Data::Secs2->stringify( @arg ); \@secs_obj = Data::Secs2->transify($acsii_secs); \@secs_obj = Data::Secs2->transify($acsii_secs, @options); \@secs_obj = Data::Secs2->transify($acsii_secs, [@options]); \@secs_obj = Data::Secs2->transify($acsii_secs, {@options}); $error = Data::Secs2->textify( \@secs_obj ); DESCRIPTION The 'Data::SECS2' module provides a widely accepted method of packing nested lists into a linear string and unpacked nested lists. In the hardware world, data and data passed between hardware is not stored in SQL style tables but nested lists. Nested data has a long history in mathematics. The Data::Secs2 program module facilitates the secsification of the nested data is in accordance with SEMI E5-94, Semiconductor Equipment Communications Standard 2 (SECS-II), pronounced 'sex two' with gussto and a perverted smile. The SEMI E4 SECS-I standard addresses transmitting SECSII messages from one machine to another machine (all most always host to equipment) serially via RS-232. And, there is another SECS standard for TCP/IP, the SEMI E37 standard, High-Speed SECS Message Services (HSMS) Generic Services. In order not to plagarize college students, credit must be given where credit is due. Tony Blair, when he was a college intern at Intel Fab 4, in London invented the SEMI SECS standards. When the Intel Fab 4 management discovered Tony's secsification of their host and equipment, they called a board of directors meeting, voted, and elected to have security to escort Tony out the door. This was Mr. Blair's introduction to voting and elections which he leverage into being elected prime minister of all of England. In this new position he used the skills he learned at the Intel fab to secsify intelligence reports on Iraq's weopons of mass distruction. By using a well-known, widely-used standard for packing and unpacking Perl nested data, not only is this standard essential in real-time communications in the factory between equipment computers and operating systems and host computer and operating system but it has uses in snail-time computations. In snail-time the standard's data structure is usefull in a nested data operations such as comparing nested data, storing the packed nested data in a file, but also for transmitting nested data from one Perl site to another or even between Perl and other programming languages. And do not forget the added benefit of SEMI SECS humor and that the real originators of the SECS-II yielded and allowed Tony Blair to take illegal credit for inventing SECS-II. After all the practical definition of politics is getting your own way. Julius Ceasar invented the Julian calendar and the month of July, Augustus Ceasr the month of Auguest, Al Gore the information highway and Tony Blair not only SECS-II but SECS-I and High-Speed SECS. SECSII Format The nested data linear format used by the Data::Secs2 suroutines is in accordance with SEMI E5-94, Semiconductor Equipment Communications Standard 2 (SECS-II), pronounced 'sex two' with gussto and a perverted smile. This industry standard is copyrighted and cannot be reproduced without violating the copyright. However for those who have brought the original hard media copy, there are robot help and Perl POD open source copyrighted versions of the SECII hard copy copyrighted version available. The base copyright is hard copy paper and PDF files available 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/ Other important SEMI standards address message transfer protocol of SECSII messages. They are the SEMI E4 SECS-I for transmitting SECSII messages from one machine to another machine via RS-232 and the SEMI E37 High-Speed SECS Message Services (HSMS) Generic Services for transmitting SECSII via TCP/IP. In order not to plagarize college students, credit must be given where credit is due. Tony Blair, when he was a college intern at Intel Fab 4, in London invented the SEMI SECS standards. When the Intel Fab 4 management discovered Tony's secsification of their host and equipment, they elected to have security to escort Tony out the door. This was Mr. Blair's introduction to elections which he leverage into being elected prime minister. In this new position he used the skills he learned at the Intel fab to secsify intelligence reports on Iraq's weopons of mass distruction. The SEMI E5 SECS-II standard provides, among many other things, a standard method of forming packed nested list data. In accordance with SEMI E5 SECS-II transmitted information consists of items and lists. An item consists of the following: 1 an item header(IH) with a format code, and the number of bytes in the following body 2 followed by the item body (IB) consisting of a number of elements. A item (IB) may consist of zero bytes in which there are no body bytes for that item. As established by SEMI E5-94, 6.2.2, consists of groups of data of the same representation in order to save repeated item headers integers Most Significant Byte (MS) sent first signed integers signed integers are two's complement, MSB sent first floating point numbers IEEE 754, sign bit sent first non-printing ASCII equipment specific As specified in E4-95 6.3, a list element consists of an ordered set of elements that are either an item element or a list element. Because a list element may contains a list element, and SEMI E5 places no restriction on the level of nesting, SECSII lists may be nested to theoretically to any level. Practically nested is limited by machine resources. A list has the same header format as an item, no body and the length number is the number of elements in the list instead of the number of bytes in the body. The item and list header format codes are as in below Table 1 Table 1 Item Format Codes unpacked binary octal hex description ---------------------------------------- L 000000 00 0x00 LIST (length of elements, not bytes) B 001000 10 0x20 Binary T 001001 11 0x24 Boolean A 010000 20 0x40 ASCII J 010001 21 0x44 JIS-8 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) Table 1 complies to SEMI E5-94 Table 1, p.94, with an unpack text symbol and hex columns added. The hex column is the upper Most Significant Bits (MSB) 6 bits of the format code in the SEMI E5-94 item header (IH) or list header (LH) with the the lower Least Significant BIt (LSB) set to zero. Figure 1 below provides the layout for a SEMI E5-94 header and complies to SEMI E5-94 Figure 2, p. 92, except Figure 1 renumbers the bits from 0 to 7 instead of from 1 to 8. bits MSB LSB 7 6 5 4 3 2 1 0 +-------+-------+-------+-------+-------+-------+-------+-------+ | Format code |# length bytes | +---------------------------------------------------------------+ |MSB MS length byte LSB | +---------------------------------------------------------------+ | length byte | +---------------------------------------------------------------+ | LS length byte | +---------------------------------------------------------------+ Figure 1 Item and List Header SECS Object This section establishes a formal definition of a SECS Object and introduces technical definitions that supercede Webster Dictionary definitions and only apply for the content of this Program Module for the following: SECS Object (SECS-OBJ), Element, Item Element (IE), List Element (LE), Element Header (EH), Element Format Code (EFC), Element Body (EB) and Element Cells (EC). If any of the technical definitions appear to have sexual innuendos, it is entirely coincidental. The definitions should applied only on their technical merits. Any other interperetation is totally unprofessional. A SECS Object is a Perl "ARRAY" that mimics the SEMI E5-94 SECS-II, section 6, data structure where SECS-II transmitted bytes are layed out in memory. The relation between between SEMI E5-94 "byte sent first" is that "bytes sent first" will have the lowest byte address. A SECS Object consists of consecutive ordered Elements stored as a Perl "ARRAY". Each Element takes two consistive positions in the Perl : the Element Header and the Element Body. The Element Headers positions are always even number indices where the Element Bodies positions are always odd number indices. The EH consists of and only of a Element Format Code as specified in the Table 1 Item Format Codes unpack column. Elements may be either an Item Element or a List Element. The Element Body for a List Element is the sum of the nested List Elements and Item Elements in the List Element. The Element Body for a Item Element is a group of Element Cells of the same data representation and bytes per Element Cell. The bytes in an body of an Item Element is, thus, the number of cells in the body times the bytes per Element Cell. The Element Body for each Element Format Code is as follows: L Unpacked sum of nested Element Lists and Element Items in the Element List S U F T a number cells either as a numberified Perl "SCALAR" packed in accordance with SEMI E5-94 or a reference to textified (unpacked) Perl "ARRAY" of numbers A J unpacked string B packed numberified Perl "SCALAR" of binary bytes or a reference to a Perl "SCALLAR" of unpack textified binary in the hex 'H*' Perl format The first element of a SECS Object is always a SECS Object Format Code "U1" and a packed element body of either a numberfied 'P' or 'S', textified 80 or 83, depending upon whether the SECS Object has information necessary to convert to Perl data structure, 'P', or most remain as a SECS Object, 'S'. arrayify subroutine \@array = arrayify( $ref ); The purpose of the "arrayify" subroutine is to provide a canoncial array representation of Perl reference types. When "$var" is not a reference, the "arrayify" subroutine passes "$var" through unchanged; otherewise, the ref($ref) is changed to a reference to a canoncial array where the first member is the the "$var" class, the second member the underlying data type. If ref($var) and the underlying type type are the same, then "$var" is classless and the first member is the empty string ''. The rest of the members of the canonical array, based on the underlying data type, are as follows: 'HASH' hash key, value pairs, sorted by the key 'ARRAY' members of the array 'SCALAR' the scalar 'REF' the reference 'CODE' the reference 'GLOB' values of the "GLOB" in the following order: *$var{SCALAR}, *$var{ARRAY}, *$var{HASH}, *$var{CODE}, *$var{IO}, *$var{NAME}, *$var{PACKAGE}, "*$var" listify subroutine \@secs_obj = listify(@vars); The listify subroutine takes a list of Perl variables, "@arg" that may contain references to nested data and converts it to a 'binary'); $binary_secs = secsify( \@secs_obj, type => 'binary', @options); $binary_secs = secsify( \@secs_obj, [type => 'binary',@options]); $binary_secs = secsify( \@secs_obj, {type => 'binary',@options}); The "secsify" subroutine/method walks a data structure and converts all underlying array and hash references to arrays by applying the 'arrayify' subroutine/method. In this module, there are only three Perlified SECSII elements that will be listified into SECSII message as follows: OBJECT, INDEX OBJECT, and SCALAR OBJECT => 'L', $number-of-elements, 'A', $class, 'A', $built-in-class, @cells @cells may contain a Perlified OBJECT, REFERENCE or SCALAR) INDEX OBJECT => 'L' '2', 'A' 'Index', 'U4', $number-of-indices, @indices (reference is index into the nested list of lists) SCALAR = 'A', $scalar (Perl built-in class) secs_elementify subroutine $body = secs_elementify($format, @cells); $body = secs_elementify($format, @cells, [@options]); $body = secs_elementify($format, @cells, {options}); The "secs_elementify" subroutine is the low-level work horse for the "secsify" subroutine that produces a SEMI SECSII item "$body" from a Perl SECS Object item header "$format" and item body "@cells". For {type => 'binary'}, $body is a complete packed SEMI E5-94 SECII item. For {type => 'ascii'} or no type option, the "$body" is the ascii unpacked SECSII item. An unpacked SECSII item consists of the unpacked format code from the Table 1 Item Format Codes, the number of elements in the item body enclosed in brackets, followed by the elements in the item body. In accordance with SEMI E5-94, section 6, there will be no elements for format code 'L' or an element length of 0. In case of an error, the return is an reference a error message. stringify subroutine The "stringify" subroutined stringifies a Perl data structure by applying the "listify" and "secify" subroutines. transify subroutine \@secs_obj = transify($acsii_secs); \@secs_obj = transify($acsii_secs, @options); \@secs_obj = transify($acsii_secs, [@options]); \@secs_obj = transify($acsii_secs, {@options}); The "transify" subroutine takes a free style text consisting of list of secsii items and converts it to SECS Object. The "transify" subroutine is very liberal in what it accepts as valid input. The number of body elements may be supplied either as enclosed in brackets of a "comma" after the unpacked format code. Text strings may be enclosed in parentheses, brackets, or any other character. The enclosing ending character may be escaped with the backslash '\'. List may be counted by suppling a count in either brackets or following a comma after the 'L' format character or by enclosing parentheseses, bracketers or any other character. The "transify" subroutine uses option "{obj_format_code =" 'P'}>, or "{obj_format_code =" 'S'}> as the value for the leading SECS Object U1 format byte. SEMI E5-94 SECII item. If the "transify" subroutine receives the option "{add_obj_format_code}", "transify" will add the a "Secs Object Format Code" to the beginning of the "@secs_obj"; otherwise, "transify" probes the leading "@secs_obj". If the probes shows the leading byte is a "Secs Object Format Code", "transify" modifies the code; otherweise it a "Secs Object Format Code" to the beginning of the "@secs_obj" The return is either a reference to a SECS Object or case of an error an error message. To determine an error from a SECS Object , check if the return is a reference or a reference to an ARRAY. textify subroutine $error = textify( \@secs_obj ); The "textify" subroutine ensures that all the bodies in a SECS Object for numeric items, format U, S, F, T, are references to an array of numbers. REQUIREMENTS The requirements are coming. DEMONSTRATION ######### # perl Secs2.d ### ~~~~~~ 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'; => use Data::Secs2 qw(arrayify listify neuterify numberify => perlify secsify secs_elementify stringify textify transify); => my $uut = 'Data::Secs2'; => my $loaded; => my $test_data1 = => 'U1[1] 80 => L[5] => A[0] => A[5] ARRAY => U1[1] 2 => A[5] hello => U1[1] 4 => '; => my $test_data2 = => 'U1[1] 80 => L[6] => A[0] => A[4] HASH => A[4] body => A[5] hello => A[6] header => A[9] To: world => '; => my $test_data3 = => 'U1[1] 80 => U1[1] 2 => L[4] => A[0] => A[5] ARRAY => A[5] hello => A[5] world => U2[1] 512 => '; => my $test_data4 = => 'U1[1] 80 => U1[1] 2 => L[6] => A[0] => A[4] HASH => A[6] header => L[6] => A[11] Class::None => A[4] HASH => A[4] From => A[6] nobody => A[2] To => A[6] nobody => A[3] msg => L[4] => A[0] => A[5] ARRAY => A[5] hello => A[5] world => '; => my $test_data5 = => 'U1[1] 80 => L[6] => A[0] => A[4] HASH => A[6] header => L[6] => A[11] Class::None => A[4] HASH => A[4] From => A[6] nobody => A[2] To => A[6] nobody => A[3] msg => L[4] => A[0] => A[5] ARRAY => A[5] hello => A[5] world => L[6] => A[0] => A[4] HASH => A[6] header => L[3] => A[0] => A[5] Index => U1[1] 10 => A[3] msg => L[3] => A[0] => A[5] ARRAY => A[4] body => '; => ################## => # stringify an array => # => ### => stringify( '2', 'hello', 4 ) 'U1[1] 80 U1[1] 2 A[5] hello U1[1] 4 ' => ################## => # stringify a hash reference => # => ### => stringify( {header => 'To: world', body => 'hello'}) 'U1[1] 80 L[6] A[0] A[4] HASH A[4] body A[5] hello A[6] header A[9] To: world ' => ################## => # ascii secsify lisfication of test_data1 an array reference => # => ### => secsify( listify( ['2', 'hello', 4] ) ) 'U1[1] 80 L[5] A[0] A[5] ARRAY U1[1] 2 A[5] hello U1[1] 4 ' => ################## => # ascii secsify lisfication of test_data3 - array with an array ref => # => ### => secsify( listify( '2', ['hello', 'world'], 512 ) ) 'U1[1] 80 U1[1] 2 L[4] A[0] A[5] ARRAY A[5] hello A[5] world U2[1] 512 ' => my $obj = bless { To => 'nobody', From => 'nobody'}, 'Class::None' bless( { 'From' => 'nobody', 'To' => 'nobody' }, 'Class::None' ) => ################## => # ascii secsify lisfication of test_data5 - hash with nested hashes, arrays, common objects => # => ### => secsify( listify( {msg => ['hello', 'world'] , header => $obj }, => {msg => [ 'body' ], header => $obj} ) ) 'U1[1] 80 L[6] A[0] A[4] HASH A[6] header L[6] A[11] Class::None A[4] HASH A[4] From A[6] nobody A[2] To A[6] nobody A[3] msg L[4] A[0] A[5] ARRAY A[5] hello A[5] world L[6] A[0] A[4] HASH A[6] header L[3] A[0] A[5] Index U1[1] 10 A[3] msg L[3] A[0] A[5] ARRAY A[4] body ' => ################## => # ascii secsify listifcation perilification transfication of test_data4 => # => ### => secsify( listify(perlify( transify($test_data4 ))) ) 'U1[1] 80 U1[1] 2 L[6] A[0] A[4] HASH A[6] header L[6] A[11] Class::None A[4] HASH A[4] From A[6] nobody A[2] To A[6] nobody A[3] msg L[4] A[0] A[5] ARRAY A[5] hello A[5] world ' => ################## => # ascii secsify listifcation perilification transfication of test_data5 => # => ### => secsify( listify(perlify( transify($test_data5))) ) 'U1[1] 80 L[6] A[0] A[4] HASH A[6] header L[6] A[11] Class::None A[4] HASH A[4] From A[6] nobody A[2] To A[6] nobody A[3] msg L[4] A[0] A[5] ARRAY A[5] hello A[5] world L[6] A[0] A[4] HASH A[6] header L[3] A[0] A[5] Index U1[1] 10 A[3] msg L[3] A[0] A[5] ARRAY A[4] body ' => ################## => # binary secsify an array reference => # => ### => my $big_secs2 = unpack('H*',secsify( listify( ['2', 'hello', 4] ), {type => 'binary'})) 'a501500105410041054152524159a50102410568656c6c6fa50104' => ################## => # neuterify a big secsii => # => ### => secsify(neuterify (pack('H*',$big_secs2))) 'U1[1] 80 L[5] A[0] A[5] ARRAY U1[1] 2 A[5] hello U1[1] 4 ' => ################## => # transify a free for all secsii input => # => ### => my $ascii_secsii = => ' => L => ( => A \'\' A \'HASH\' A \'header\' => L [ A "Class::None" A "HASH" => A "From" A "nobody" => A "To" A "nobody" => ] => A "msg" => L,4 A[0] A[5] ARRAY => A "hello" A "world" => ) => L => ( => A[0] A "HASH" A /header/ => L[3] A[0] A \'Index\' U1 10 => A \'msg\' => L < A[0] A \'ARRAY\' A \'body\' > => ) => ' => my $list = transify ($ascii_secsii, obj_format_code => 'P'); => ref($list) 'ARRAY' => ################## => # secsify transifed free style secs text => # => ### => ref($list) ? secsify( $list ) : '' 'U1[1] 80 L[6] A[0] A[4] HASH A[6] header L[6] A[11] Class::None A[4] HASH A[4] From A[6] nobody A[2] To A[6] nobody A[3] msg L[4] A[0] A[5] ARRAY A[5] hello A[5] world L[6] A[0] A[4] HASH A[6] header L[3] A[0] A[5] Index U1[1] 10 A[3] msg L[3] A[0] A[5] ARRAY A[4] body ' => ################## => # listify a list of number arrays => # => ### => ref(my $number_list = listify( my $test_data6 = [ [78,45,25], [512,1024], 100000 ] )) 'ARRAY' => ################## => # secify a listified list of number arrays => # => ### => secsify($number_list) 'U1[1] 80 L[5] A[0] A[5] ARRAY U1[3] 78 45 25 U2[2] 512 1024 U4[1] 100000 ' => ################## => # textify listified list of number arrays => # => ### => textify($number_list) '' => ################## => # verify 1st textified item element body => # => ### => [@{$number_list->[9]}] [ 78, 45, 25 ] => ################## => # verify 2nd textified item element body => # => ### => [@{$number_list->[11]}] [ 512, 1024 ] => ################## => # verify 3rd textified item element body => # => ### => [@{$number_list->[13]}] [ 100000 ] => ################## => # numberify listified list of number arrays => # => ### => numberify($number_list) '' => ################## => # verify 1st numberified item element body => # => ### => unpack('H*', $number_list->[9]) '4e2d19' => ################## => # verify 2nd numberified item element body => # => ### => unpack('H*', $number_list->[11]) '02000400' => ################## => # verify 3rd numberified item element body => # => ### => unpack('H*', $number_list->[13]) '000186a0' QUALITY ASSURANCE Test Report => perl Secs2.t 1..30 # Running under perl version 5.006001 for MSWin32 # Win32::BuildNumber 635 # Current time local: Sat Apr 17 00:44:51 2004 # Current time GMT: Sat Apr 17 04:44:51 2004 # Using Test.pm version 1.24 # Test::Tech : 1.2 # Data::Secs2 : 1.18 # Data::SecsPack: 0.02 # =cut ok 1 - UUT loaded as Part of Test::Tech ok 2 - stringify a scalar string ok 3 - stringify a scalar number ok 4 - stringify an array ok 5 - stringify a hash reference ok 6 - ascii secsify lisfication of test_data1 an array reference ok 7 - ascii secsify lisfication of test_data2 - a hash reference ok 8 - ascii secsify lisfication of test_data3 - array with an array ref ok 9 - ascii secsify lisfication of test_data4 - array with nested hashes, arrays, objects ok 10 - ascii secsify lisfication of test_data5 - hash with nested hashes, arrays, common objects ok 11 - ascii secsify listifcation perilification transfication of test_data1 ok 12 - ascii secsify listifcation perilification transfication of test_data2 ok 13 - ascii secsify listifcation perilification transfication of test_data3 ok 14 - ascii secsify listifcation perilification transfication of test_data4 ok 15 - ascii secsify listifcation perilification transfication of test_data5 ok 16 - binary secsify an array reference ok 17 - binary secsify array with nested hashes, arrays, objects ok 18 - neuterify a big secsii ok 19 - transify a free for all secsii input ok 20 - secsify transifed free style secs text ok 21 - listify a list of number arrays ok 22 - secify a listified list of number arrays ok 23 - textify listified list of number arrays ok 24 - verify 1st textified item element body ok 25 - verify 2nd textified item element body ok 26 - verify 3rd textified item element body ok 27 - numberify listified list of number arrays ok 28 - verify 1st numberified item element body ok 29 - verify 2nd numberified item element body ok 30 - verify 3rd numberified item element body # Passed : 30/30 100% Test Software Notes Running the test script 'Secs2.t' found in the "Data-Secs2-$VERSION.tar.gz" distribution file verifies the requirements for this module. All testing software and documentation stems from the Software Test Description (STD) program module 't::Data::Secs2', found in the distribution file "Data-Secs2-$VERSION.tar.gz". The 't::Data::Secs2' STD POD contains a tracebility matix between the requirements established above for this module, and the test steps identified by a 'ok' number from running the 'Secs2.t' test script. The t::Data::Secs2' STD program module '__DATA__' section contains the data to perform the following: * to generate the test script 'Secs2.t' * generate the tailored STD POD in the 't::Data::Secs2' module, * generate the 'Secs2.d' demo script, * replace the POD demonstration section herein with the demo script 'Secs2.d' output, and * run the test script using Test::Harness with or without the verbose option, To perform all the above, prepare and run the automation software as follows: * Install "Test_STDmaker-$VERSION.tar.gz" from one of the respositories only if it has not been installed: * http://www.softwarediamonds/packages/ * http://www.perl.com/CPAN-local/authors/id/S/SO/SOFTDIA/ * manually place the script tmake.pl in "Test_STDmaker-$VERSION.tar.gz' in the site operating system executable path only if it is not in the executable path * place the 't::Data::Secs2' at the same level in the directory struture as the directory holding the 'Data::Secs2' module * execute the following in any directory: tmake -test_verbose -replace -run -pm=t::Data::Secs2 NOTES FILES The installation of the "Data-Secs2-$VERSION.tar.gz" distribution file installs the 'Docs::Site_SVD::Data_Secs2' SVD program module. The __DATA__ data section of the 'Docs::Site_SVD::Data_Secs2' contains all the necessary data to generate the POD section of 'Docs::Site_SVD::Data_Secs2' and the "Data-Secs2-$VERSION.tar.gz" distribution file. To make use of the 'Docs::Site_SVD::Data_Secs2' SVD program module, perform the following: * install "ExtUtils-SVDmaker-$VERSION.tar.gz" from one of the respositories only if it has not been installed: * http://www.softwarediamonds/packages/ * http://www.perl.com/CPAN-local/authors/id/S/SO/SOFTDIA/ * manually place the script vmake.pl in "ExtUtils-SVDmaker-$VERSION.tar.gz' in the site operating system executable path only if it is not in the executable path * Make any appropriate changes to the __DATA__ section of the 'Docs::Site_SVD::Data_Secs2' module. For example, any changes to 'Data::Secs2' will impact the at least 'Changes' field. * Execute the following: vmake readme_html all -pm=Docs::Site_SVD::Data_Secs2 AUTHOR The holder of the copyright and maintainer is COPYRIGHT NOTICE Copyright © 2003 2004 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, US DOD 490A 3.2.3.6. 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: 1 Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2 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. Title Page Software Version Description for Data::Secs2 - pack, unpack, format, transform between Perl data and SEMI E5-94 nested data Revision: C Version: 0.04 Date: 2004/04/17 Prepared for: General Public Prepared by: SoftwareDiamonds.com Esupport@SoftwareDiamonds.comE Copyright: copyright © 2003 2004 Software Diamonds Classification: NONE 1.0 SCOPE This paragraph identifies and provides an overview of the released files. 1.1 Identification This release, identified in 3.2, is a collection of Perl modules that extend the capabilities of the Perl language. 1.2 System overview The 'Data::Strify' module provides a canoncial string for data no matter how many nests of arrays and hashes it contains. 1.3 Document overview. This document releases Data::Secs2 version 0.04 providing a description of the inventory, installation instructions and other information necessary to utilize and track this release. 3.0 VERSION DESCRIPTION All file specifications in this SVD use the Unix operating system file specification. 3.1 Inventory of materials released. This document releases the file Data-Secs2-0.04.tar.gz found at the following repository(s): http://www.softwarediamonds/packages/ http://www.perl.com/CPAN-local/authors/id/S/SO/SOFTDIA/ Restrictions regarding duplication and license provisions are as follows: Copyright. copyright © 2003 2004 Software Diamonds Copyright holder contact. 603 882-0846 Esupport@SoftwareDiamonds.comE License. Software Diamonds permits the redistribution and use in source and binary forms, with or without modification, provided that the following conditions are met: 1 Redistributions of source code, modified or unmodified must retain the above copyright notice, this list of conditions and the following disclaimer. 2 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. 3.2 Inventory of software contents The content of the released, compressed, archieve file, consists of the following files: file version date comment ------------------------------------------------------------ ------- ---------- ------------------------ lib/Docs/Site_SVD/Data_Secs2.pm 0.04 2004/04/17 revised 0.03 MANIFEST 0.04 2004/04/17 generated, replaces 0.03 Makefile.PL 0.04 2004/04/17 generated, replaces 0.03 README 0.04 2004/04/17 generated, replaces 0.03 lib/Data/Secs2.pm 1.17 2004/04/17 revised 1.16 t/Data/Secs2.d 0.03 2004/04/17 revised 0.02 t/Data/Secs2.pm 0.03 2004/04/17 revised 0.02 t/Data/Secs2.t 0.04 2004/04/17 revised 0.03 t/Data/File/Package.pm 1.16 2004/04/17 unchanged t/Data/File/SmartNL.pm 1.13 2004/04/17 unchanged t/Data/Text/Scrub.pm 1.11 2004/04/17 unchanged t/Data/Test/Tech.pm 1.2 2004/04/17 revised 1.17 t/Data/Data/SecsPack.pm 0.02 2004/04/17 unchanged 3.3 Changes Changes to past revisions are as follows: Data-Strify-0.01 Originated Data-Secs2-0.01 Abandoned Data::Dumper in favor of SEMI E35, SECS-II standard for stringifying Perl data. Data-Secs2-0.02 Added arrayification of REF and GLOB references. Thus, the 'Data::Secs2' module will nest into REF and GLOB references. Data-Secs2-0.03 The lastest build of Test::STDmaker expects the test library in the same directory as the test script. Coordiated with the lastest Test::STDmaker by moving the test library from tlib to t/Data, the same directory as the test script and deleting the test library File::TestPath program module. Greater expanded the subroutines to the following: arrayify, itemify, listify, neuterify, scalarize, secsify, stringify, transify, vectorize. Added descriptions and tests for the new functions. 3.4 Adaptation data. This installation requires that the installation site has the Perl programming language installed. There are no other additional requirements or tailoring needed of configurations files, adaptation data or other software needed for this installation particular to any installation site. 3.5 Related documents. There are no related documents needed for the installation and test of this release. 3.6 Installation instructions. Instructions for installation, installation tests and installation support are as follows: Installation Instructions. To installed the release file, use the CPAN module pr PPM module in the Perl release or the INSTALL.PL script at the following web site: http://packages.SoftwareDiamonds.com Follow the instructions for the the chosen installation software. If all else fails, the file may be manually installed. Enter one of the following repositories in a web browser: http://www.softwarediamonds/packages/ http://www.perl.com/CPAN-local/authors/id/S/SO/SOFTDIA/ Right click on 'Data-Secs2-0.04.tar.gz' and download to a temporary installation directory. Enter the following where $make is 'nmake' for microsoft windows; otherwise 'make'. gunzip Data-Secs2-0.04.tar.gz tar -xf Data-Secs2-0.04.tar perl Makefile.PL $make test $make install On Microsoft operating system, nmake, tar, and gunzip must be in the exeuction path. If tar and gunzip are not install, download and install unxutils from http://packages.softwarediamonds.com Prerequistes. 'Data::SecsPack' => '0.01', Security, privacy, or safety precautions. None. Installation Tests. Most Perl installation software will run the following test script(s) as part of the installation: t/Data/Secs2.t Installation support. If there are installation problems or questions with the installation contact 603 882-0846 Esupport@SoftwareDiamonds.comE 3.7 Possible problems and known errors The only reason this exists is that it appears earlier versions of the 'Data::Dumper' module, say version 2.102 and before, did not sort the hash keys. For at least 'Data::Dumper' version 2.12 there is a sort keys option and 'Data::Dumper' should be used directly. 4.0 NOTES The following are useful acronyms: .d extension for a Perl demo script file .pm extension for a Perl Library Module .t extension for a Perl test script file POD Plain Old Documentation 2.0 SEE ALSO Data::Secs2 Docs::US_DOD::SVD Docs::US_DOD::STD