home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Database Designers / Rational Rose 2000 / Rational Setup.EXE / common / lib / Win32 / OLE / Variant.pm < prev   
Encoding:
Perl POD Document  |  1998-11-15  |  7.0 KB  |  263 lines
  1. # The documentation is at the __END__
  2.  
  3. package Win32::OLE::Variant;
  4. require Win32::OLE;  # Make sure the XS bootstrap has been called
  5.  
  6. use strict;
  7. use vars qw(@ISA @EXPORT @EXPORT_OK $CP $LCID $LastError $Warn);
  8.  
  9. use Exporter;
  10. @ISA = qw(Exporter);
  11.  
  12. @EXPORT = qw(
  13.          Variant
  14.          VT_EMPTY VT_NULL VT_I2 VT_I4 VT_R4 VT_R8 VT_CY VT_DATE VT_BSTR
  15.          VT_DISPATCH VT_ERROR VT_BOOL VT_VARIANT VT_UNKNOWN VT_UI1
  16.          VT_BYREF
  17.         );
  18.  
  19. @EXPORT_OK = qw(CP_ACP CP_OEMCP);
  20.  
  21. # Automation data types.
  22. sub VT_EMPTY {0;}
  23. sub VT_NULL {1;}
  24. sub VT_I2 {2;}
  25. sub VT_I4 {3;}
  26. sub VT_R4 {4;}
  27. sub VT_R8 {5;}
  28. sub VT_CY {6;}
  29. sub VT_DATE {7;}
  30. sub VT_BSTR {8;}
  31. sub VT_DISPATCH {9;}
  32. sub VT_ERROR {10;}
  33. sub VT_BOOL {11;}
  34. sub VT_VARIANT {12;}
  35. sub VT_UNKNOWN {13;}
  36. sub VT_UI1 {17;}
  37.  
  38. sub VT_BYREF {0x4000;}
  39.  
  40. # Codepages
  41. sub CP_ACP {0;}
  42. sub CP_OEMCP {1;}
  43.  
  44. # Package variables
  45. $Warn = $^W;
  46. $CP   = CP_ACP;
  47. $LCID = 2 << 10; # LOCALE_SYSTEM_DEFAULT
  48.  
  49. # following subs are pure XS code:
  50. # - new(type,data)
  51. # - As(type)
  52. # - ChangeType(type)
  53. # - Unicode
  54.  
  55. use overload '""'     => sub {$_[0]->As(VT_BSTR)},
  56.              '0+'     => sub {$_[0]->As(VT_R8)},
  57.              fallback => 1; 
  58.  
  59. sub LastError {
  60.     no strict 'refs';
  61.     my $LastError = "$_[0]::LastError";
  62.     $$LastError = $_[1] if defined $_[1];
  63.     return $$LastError;
  64. }
  65.  
  66. sub Variant {
  67.     return Win32::OLE::Variant->new(@_);
  68. }
  69.  
  70. 1;
  71.  
  72. __END__
  73.  
  74. =head1 NAME
  75.  
  76. Win32::OLE::Variant - Create and modify OLE VARIANT variables
  77.  
  78. =head1 SYNOPSIS
  79.  
  80.     use Win32::OLE::Variant;
  81.     my $var = Variant(VT_DATE, 'Jan 1,1970');
  82.     $OleObject->{value} = $var;
  83.     $OleObject->Method($var);
  84.  
  85.  
  86. =head1 DESCRIPTION
  87.  
  88. The IDispatch interface used by the Perl OLE module uses a universal
  89. argument type called VARIANT. This is basically an object containing
  90. a data type and the actual data value. The data type is specified by
  91. the VT_xxx constants.
  92.  
  93. =head2 Methods
  94.  
  95. =over 8
  96.  
  97. =item new(TYPE, DATA)
  98.  
  99. This method returns a Win32::OLE::Variant object of the specified
  100. type that contains the given data.  The Win32::OLE::Variant object
  101. can be used to specify data types other than IV, NV or PV (which are
  102. supported transparently).  See L<Variants> below for details.
  103.  
  104. =item As(TYPE)
  105.  
  106. C<As> converts the VARIANT to the new type before converting to a
  107. Perl value. This take the current LCID setting into account. For
  108. example a string might contain a ',' as the decimal point character.
  109. Using C<$variant->As(VT_R8)> will correctly return the floating
  110. point value.
  111.  
  112. The underlying variant object is NOT changed by this method.
  113.  
  114. =item ChangeType(TYPE)
  115.  
  116. This method changes the type of the contained VARIANT in place. It
  117. returns the object itself, not the converted value.
  118.  
  119. =item LastError()
  120.  
  121. The C<LastError> method returns the last recorded OLE error in the
  122. Win32::OLE::Variant class. This is dual value like the C<$!> variable:
  123. in a numeric context it returns the error number and in a string
  124. context it returns the error message.
  125.  
  126. The method corresponds to the C<Win32::OLE->LastError> method for
  127. Win32::OLE objects.
  128.  
  129. =item Type()
  130.  
  131. The C<Type> method returns the type of the contained VARIANT.
  132.  
  133. =item Unicode()
  134.  
  135. The C<Unicode> method returns a C<Unicode::String> object. This contains
  136. the BSTR value of the variant in network byte order. If the variant is
  137. not currently in VT_BSTR format then a VT_BSTR copy will be produced first.
  138.  
  139. =item Value()
  140.  
  141. The C<Value> method returns the value of the VARIANT as a Perl value. The
  142. conversion is performed in the same manner as all return values of
  143. Win32::OLE method calls are converted.
  144.  
  145. =back
  146.  
  147. =head2 Functions
  148.  
  149. =over 8
  150.  
  151. =item Variant(TYPE, DATA)
  152.  
  153. This is just a function alias of the Win32::OLE::Variant->new()
  154. method. This function is exported by default.
  155.  
  156. =back
  157.  
  158. =head2 Overloading
  159.  
  160. The Win32::OLE::Variant package has overloaded the conversion to
  161. string an number formats. Therefore variant objects can be used in
  162. arithmetic and string operations without applying the C<Value> 
  163. method first.
  164.  
  165. =head2 Class Variables
  166.  
  167. This module supports the C<$CP>, C<$LCID> and C<$Warn> class variables.
  168. They have the same meaning as the variables in L<Win32::OLE> of the
  169. same name.
  170.  
  171. =head2 Constants
  172.  
  173. These constants are exported by default:
  174.  
  175.     VT_EMPTY
  176.     VT_NULL
  177.     VT_I2
  178.     VT_I4
  179.     VT_R4
  180.     VT_R8
  181.     VT_CY
  182.     VT_DATE
  183.     VT_BSTR
  184.     VT_DISPATCH
  185.     VT_ERROR
  186.     VT_BOOL
  187.     VT_VARIANT
  188.     VT_UNKNOWN
  189.     VT_UI1
  190.     VT_BYREF
  191.  
  192. =head2 Variants
  193.  
  194. A Variant is a data type that is used to pass data between OLE
  195. connections.
  196.  
  197. The default behavior is to convert each perl scalar variable into
  198. an OLE Variant according to the internal perl representation.
  199. The following type correspondence holds:
  200.  
  201.         C type          Perl type       OLE type
  202.         ------          ---------       --------
  203.           int              IV            VT_I4
  204.         double             NV            VT_R8
  205.         char *             PV            VT_BSTR
  206.         void *           ref to AV       VT_ARRAY
  207.            ?              undef          VT_ERROR
  208.            ?        Win32::OLE object    VT_DISPATCH
  209.  
  210. Note that VT_BSTR is a wide character or Unicode string.  This presents a
  211. problem if you want to pass in binary data as a parameter as 0x00 is
  212. inserted between all the bytes in your data. The C<Variant()> method
  213. provides a solution to this.  With Variants the script
  214. writer can specify the OLE variant type that the parameter should be
  215. converted to.  Currently supported types are:
  216.  
  217.         VT_UI1     unsigned char
  218.         VT_I2      signed int (2 bytes)
  219.         VT_I4      signed int (4 bytes)
  220.         VT_R4      float      (4 bytes)
  221.         VT_R8      float      (8 bytes)
  222.         VT_DATE    OLE Date
  223.         VT_BSTR    OLE String
  224.         VT_CY      OLE Currency
  225.         VT_BOOL    OLE Boolean
  226.  
  227. When VT_DATE and VT_CY objects are created, the input
  228. parameter is treated as a Perl string type, which is then converted
  229. to VT_BSTR, and finally to VT_DATE of VT_CY using the VariantChangeType()
  230. OLE API function.  See L<Win32::OLE/EXAMPLES> for how these types
  231. can be used.
  232.  
  233. =head2 Variants by reference
  234.  
  235. Some OLE servers expect parameters passed by reference so that they
  236. can be changed in the method call. This allows methods to easily
  237. return multiple values. There is preliminary support for this in
  238. the Win32::OLE::Variant module:
  239.  
  240.     my $x = Variant(VT_I4|VT_BYREF, 0);
  241.     my $y = Variant(VT_I4|VT_BYREF, 0);
  242.     $Corel->GetSize($x, $y);
  243.     print "Size is $x by $y\n";
  244.  
  245. After the C<GetSize> method call C<$x> and C<$y> will be set to
  246. the respective sizes. They will still be variants. In the print
  247. statement the overloading converts them to string representation
  248. automatically.
  249.  
  250. This currently works for integer, number and BSTR variants. It can
  251. also be used to pass an OLE object by reference:
  252.  
  253.     my $Results = $App->CreateResultsObject;
  254.     $Object->Method(Variant(VT_DISPATCH|VT_BYREF, $Results));
  255.  
  256. Don't try VT_BYREF with VT_ARRAY variants (yet).
  257.  
  258. =head1 AUTHORS/COPYRIGHT
  259.  
  260. This module is part of the Win32::OLE distribution.
  261.  
  262. =cut
  263.