5 use vars qw( @ISA $VERSION );
9 @ISA = ( 'DynaLoader' );
11 my(%Locsyms) = ( ':ID' => 'LOCAL' );
12 my(%Gblsyms) = ( ':ID' => 'GLOBAL');
21 bless { TYPE => $type }, $pkg;
30 if (($val,$table) = _getsym($name)) {
31 if ($table eq 'GLOBAL') { $Gblsyms{$name} = $val; }
32 else { $Locsyms{$name} = $val; }
34 wantarray ? ($val,$table) : $val;
38 my($self,$name,$val,$table) = @_;
40 $table = $self->{TYPE} unless $table;
41 if (_setsym($name,$val,$table)) {
42 if ($table eq 'GLOBAL') { $Gblsyms{$name} = $val; }
43 else { $Locsyms{$name} = $val; }
50 my($self,$name,$table) = @_;
52 $table = $self->{TYPE} unless $table;
53 if (_delsym($name,$table)) {
54 if ($table eq 'GLOBAL') { delete $Gblsyms{$name}; }
55 else { delete $Locsyms{$name}; }
66 %Locsyms = ( ':ID' => 'LOCAL');
67 %Gblsyms = ( ':ID' => 'GLOBAL');
69 $DoCache = $perm if defined($perm);
73 #====> TIEHASH methods
81 if ($name eq ':GLOBAL') { $self->{TYPE} eq 'GLOBAL'; }
82 elsif ($name eq ':LOCAL' ) { $self->{TYPE} eq 'LOCAL'; }
83 else { scalar($self->getsym($name)); }
87 my($self,$name,$val) = @_;
88 if ($name eq ':GLOBAL') { $self->{TYPE} = 'GLOBAL'; }
89 elsif ($name eq ':LOCAL' ) { $self->{TYPE} = 'LOCAL'; }
90 else { $self->setsym($name,$val); }
103 if (!$DoCache || !$Cache_set) {
104 # We should eventually replace this with a C routine which walks the
105 # CLI symbol table directly. If I ever get 'hold of an I&DS manual . . .
106 open(P,'Show Symbol * |');
108 ($name,$eqs,$val) = /^\s+(\S+) (=+) (.+)/
109 or carp "VMS::CLISym: unparseable line $_";
111 $val =~ s/"(.*)"$/$1/ or $val =~ s/^(\S+).*/$1/;
112 if ($eqs eq '==') { $Gblsyms{$name} = $val; }
113 else { $Locsyms{$name} = $val; }
119 $self->{CACHE} = $self->{TYPE} eq 'GLOBAL' ? \%Gblsyms : \%Locsyms;
120 while (($name,$val) = each(%{$self->{CACHE}}) and !defined($name)) {
121 if ($self->{CACHE}{':ID'} eq 'GLOBAL') { return undef; }
122 $self->{CACHE} = \%Gblsyms;
131 while (($name,$val) = each(%{$self->{CACHE}}) and !defined($name)) {
132 if ($self->{CACHE}{':ID'} eq 'GLOBAL') { return undef; }
133 $self->{CACHE} = \%Gblsyms;
139 sub EXISTS { defined($_[0]->FETCH(@_)) ? 1 : 0 }
144 bootstrap VMS::DCLsym;
152 VMS::DCLsym - Perl extension to manipulate DCL symbols
156 tie %allsyms, VMS::DCLsym;
157 tie %cgisyms, VMS::DCLsym, 'GLOBAL';
160 $handle = new VMS::DCLsyms;
161 $value = $handle->getsym($name);
162 $handle->setsym($name,$value,'GLOBAL') or die "Can't create symbol: $!\n";
163 $handle->delsym($name,'LOCAL') or die "Can't delete symbol: $!\n";
164 $handle->clearcache();
168 The VMS::DCLsym extension provides access to DCL symbols using a
169 tied hash interface. This allows Perl scripts to manipulate symbols in
170 a manner similar to the way in which logical names are manipulated via
171 the built-in C<%ENV> hash. Alternatively, one can call methods in this
172 package directly to read, create, and delete symbols.
174 =head2 Tied hash interface
176 This interface lets you treat the DCL symbol table as a Perl associative array,
177 in which the key of each element is the symbol name, and the value of the
178 element is that symbol's value. Case is not significant in the key string, as
179 DCL converts symbol names to uppercase, but it is significant in the value
180 string. All of the usual operations on associative arrays are supported.
181 Reading an element retrieves the current value of the symbol, assigning to it
182 defines a new symbol (or overwrites the old value of an existing symbol), and
183 deleting an element deletes the corresponding symbol. Setting an element to
184 C<undef>, or C<undef>ing it directly, sets the corresponding symbol to the null
185 string. You may also read the special keys ':GLOBAL' and ':LOCAL' to find out
186 whether a default symbol table has been specified for this hash (see C<table>
187 below), or set either or these keys to specify a default symbol table.
189 When you call the C<tie> function to bind an associative array to this package,
190 you may specify as an optional argument the symbol table in which you wish to
191 create and delete symbols. If the argument is the string 'GLOBAL', then the
192 global symbol table is used; any other string causes the local symbol table to
193 be used. Note that this argument does not affect attempts to read symbols; if
194 a symbol with the specified name exists in the local symbol table, it is always
195 returned in preference to a symbol by the same name in the global symbol table.
197 =head2 Object interface
199 Although it's less convenient in some ways than the tied hash interface, you
200 can also call methods directly to manipulate individual symbols. In some
201 cases, this allows you finer control than using a tied hash aggregate. The
202 following methods are supported:
206 This creates a C<VMS::DCLsym> object which can be used as a handle for later
207 method calls. The single optional argument specifies the symbol table used
208 by default in future method calls, in the same way as the optional argument to
209 C<tie> described above.
213 If called in a scalar context, C<getsym> returns the value of the symbol whose
214 name is given as the argument to the call, or C<undef> if no such symbol
215 exists. Symbols in the local symbol table are always used in preference to
216 symbols in the global symbol table. If called in an array context, C<getsym>
217 returns a two-element list, whose first element is the value of the symbol, and
218 whose second element is the string 'GLOBAL' or 'LOCAL', indicating the table
219 from which the symbol's value was read.
223 The first two arguments taken by this method are the name of the symbol and the
224 value which should be assigned to it. The optional third argument is a string
225 specifying the symbol table to be used; 'GLOBAL' specifies the global symbol
226 table, and any other string specifies the local symbol table. If this argument
227 is omitted, the default symbol table for the object is used. C<setsym> returns
228 TRUE if successful, and FALSE otherwise.
232 This method deletes the symbol whose name is given as the first argument. The
233 optional second argument specifies the symbol table, as described above under
234 C<setsym>. It returns TRUE if the symbol was successfully deleted, and FALSE
239 Because of the overhead associated with obtaining the list of defined symbols
240 for the tied hash iterator, it is only done once, and the list is reused for
241 subsequent iterations. Changes to symbols made through this package are
242 recorded, but in the rare event that someone changes the process' symbol table
243 from outside (as is possible using some software from the net), the iterator
244 will be out of sync with the symbol table. If you expect this to happen, you
245 can reset the cache by calling this method. In addition, if you pass a FALSE
246 value as the first argument, caching will be disabled. It can be reenabled
247 later by calling C<clearcache> again with a TRUE value as the first argument.
248 It returns TRUE or FALSE to indicate whether caching was previously enabled or
249 disabled, respectively.
251 This method is a stopgap until we can incorporate code into this extension to
252 traverse the process' symbol table directly, so it may disappear in a future
253 version of this package.
257 Charles Bailey bailey@genetics.upenn.edu
265 The list of symbols for the iterator is assembled by spawning off a
266 subprocess, which can be slow. Ideally, we should just traverse the
267 process' symbol table directly from C.