PerlWare::Buf_T


Methods

These metods are present in the module PerlWare::Buf_T

new

Creates a new buffer for holding data to be sent or retrieved from NDS.
Example:
$Buf = new PerlWare::Buf_T;

AddObject

Create a object called $ObjectName (You'll have to use methods for adding data to the buf before calling AddObject)
Returns $iter which can be used in sequensiell calls.
Returns undef on failure, in which case you can use LastErr() to get the netware error-code.
Example:
$iter = $Buf->AddObject($ContextHandle, $ObjectName, $iter, $more);

AddPartition

Creates the root object of a new NDS partition but is now obsolete. The server parameter identifies the server where the master replica of the new partition is to be stored. Call AddReplica() and SplitPartition() instead.
Returns $iter which can be used in sequensiell calls.
Returns undef on failure, in which case you can use LastErr() to get the netware error-code.
Example:
$iter = AddPartition($ContextHandle, $server, $partitionRoot, $iter, $more);

AllocBuf

Alloc memory to hold values you specify with Put* methods With no args the alloced space is a default defined as 4096 bytes. You can also feed it $Size (Integer value) to set a custom size. The maximum size of this buffer is 64512 bytes. A smaller buffer means multiple iterations of an operation might need to be performed to retrieve all of the operation's results. On the other hand, using a large buffer might allow the operation to be completed in one step, but cause a significant delay for the user.
Returns 0 on success, Netware error code on failure.
Examples:
$ErrCode = $Buf->AllocBuf();
$ErrCode = $Buf->AllocBuf(20480);
$ErrCode = $Buf->AllocBuf($Size);

Compare

Compare the attributes stored in $Buf with the attributes associated with object $ObjectName. The value of $match give the result of the compare.
0 : No match.
non-zero : Match.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
$match = $Buf->Compare($ContextHandle, $ObjectName);
$match = $Buf->Compare($ContextHandle, 'bad.someou.someo');

Debug

This method set the internal debugging of a class to a given level. Only 0 and and 1 are in use in version 1.00.
0: OFF
1: ON
Example:
$Buf->Debug(1);

FreeBuf

Frees the memory allocated for internal structs, giving you a chance to make the buffer larger or smaller. Use InitBuf() to initiate already allocated memory if you are reusing a allocated buffer.
You do not have to call this method if you don't want to resize your buffer.
The buffer is automatically freed when a class object is destroyed.
Returns 0 on success, Netware error code on failure.
Example:
$ErrCode = $Buf->FreeBuf();

GetAttrCount

Get the number of attributes stored in $Buf. The number of attributes are returned in $AttrCount.
Returns undef on error, in which case you can use LastErr() to get the netware error-code. The $Context variable
can be fetched from a PerlWare or NDSContext class object.
Example:
$AttrCount = $Buf->GetAttrCount($ContextHandle)

GetAttrName

Get the name of the attribute ($AttrName) stored in buf and the number of values associated with the attribute ($Valcount). The $syntaxID associated with this attribute is also returned and can be used to read the attribute with GetAttrVal().
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
($AttrName, $ValCount, $SyntaxId) = $Buf->GetAttrName($ContextHandle);

GetAttrVal

Return the 'human-readable' data stored in $Buf. This method require you to know what kind of data is returned: Read more about this in datatypes.txt. Returns the value as string or integer.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
$AttrVal = $Buf->GetAttrVal($CHandle, $SyntaxId);

GetConst

Returns the numeric value of a named constant. You probably need the Netware SDK to get a description of all constants.
Example:
$Value = $Buf->GetConst($ConstName);
$Value = $Buf->GetConst('DCV_NAME_CONTEXT');

GetObjectCount

Returns the number of objects stored in the buffer after a Read() in parameter $ObjectCount.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
$ObjectCount = $Buf->GetObjectCount($ContextHandle);

GetObjectName

Returns the $ObjectName, number of attributes ($AttrCount), objectFlags,  subordinateCount, modificationTime and Baseclass of a object in the buffer. If a method returns more than one variable in perl you can store the varables one by one, in an array or a combination.
($, $, $, $)=Function()
@ = Function()
($, $, @) = Function()

objectFlags : Flags for this object, see below.
subordinateCount : Indicates the number of objects subordinates to the object.
modificationTime : Indicates the time when the object was last modified.
baseClass : Indicates the base class used to create the object.

ObjectFlags can have the following values which may be ORed:
0x0001 DS_ALIAS_ENTRY
0x0002 DS_PARTITION_ROOT
0x0004 DS_CONTAINER_ENTRY
0x0008 DS_CONTAINER_ALIAS
0x0010 DS_MATCHES_LIST_FILTER
0x0020 DS_REFERENCE_ENTRY
0x0040 DS_40X_REFERENCE_ENTRY
0x0080 DS_BACKLINKED
0x0100 DS_NEW_ENTRY

Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
($ObjectName, $AttrCount, $objectFlags, $subordinateCount, $modificationTime $baseclass) = $Buf->GetObjectName($ContextHandle);
@ObjectInfo = $Buf->GetObjectName($ContextHandle);


GetPartitionInfo

GetPartitionInfo retrieves replica information from a PerlWare::Buf_T buffer filled by ListPartitions(). The information is return as an array which have the following values:

[0] : The name of the root object of a partition. Always a NDS container name
[1] : The replica type which can have the following values:

0: Master replica.
1: Read/Write replica.
2: Read only replica.
3: Partition with only a root object.
[2] : The replica state.
0 = On
1 = New
2 = Dying
3 = Locked
4 = Change type 0, 5 = Change type 1, 6 = Transition On
7 = Transition Move, 8 = Transition Split
48 = Split 0, 49 = Split 1
64 = Join 0, 65 = Join 1, 66 = Join 2
80 = Move 0, 81 = Move 1, 82 = Move 2
Se also help file for NDS Manager for more information about each state.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
($ReplicaName, $ReplicaType, $ReplicaState) = $Buf->GetPartitionInfo($ContextHandle);


GetServerName

GetServerName Returns the name of the current server, as well as the number of partitions on the server. Use ListPartitions() to fill the buffer with this infornation.
The information is returned as an array which have the following values:

[0] : The name of of the current server.
[1] : The number of replicas found on this server.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
($ServerName, $NumReplica) = $Buf->GetServerName($ContextHandle);


InitBuf

Initiates the buffer for use with a certain operation. Not all operations are supported by PerlWare.
Operations are snipped out of the Novell SDK:
 
DSV_READ ExtSyncRead, ListAttrsEffectiveRights, Read, ReadReferences
DSV_COMPARE Compare
DSV_SEARCH ExtSyncList, ExtSyncSearch, ListByClassAndName, ListContainers, PutFilter, Search (Not supported with PerlWare)
DSV_ADD_ENTRY AddObject
DSV_MODIFY_ENTRY ModifyObject
DSV_READ_ATTR_DEF ReadAttrDef
DSV_DEFINE_CLASS DefineClass
DSV_READ_CLASS_DEF ReadClassDef
 DSV_MODIFY_CLASS_DEF ModifyClassDef
DSV_LIST_CONTAINABLE_CLASSES ListContainableClasses
DSV_READ_SYNTAXES GetSyntaxDef, PutSyntaxName, and ReadSyntaxes
Returns 0 on success, Netware error code on failure.
Example:
$Buf->InitBuf($ContextHandle, $OperationName);
$Buf->InitBuf($ContextHandle, 'DSV_READ');

IsNumType

Returns TRUE (1) if attribute with $syntaxId can be returned as a integer.
Example:
$IsNum = $Buf->IsNumType($syntaxId);

IsStringType

Returns TRUE (1) if attribute with $syntaxId can be returned as string.
Example:
$IsString = $Buf->IsStringType($syntaxId);

IsMLType

Returns TRUE (1) if attribute with $syntaxId can be returned as a multiline string.
Example:
$IsML = $Buf->IsMLType($syntaxId);

LastErr

Return the last error-number from $Buf. The error-number is often an NDS error which is described if you press <F1> in NWadmin (MS Windows) and search for 'Error'.
The file is called nw_error.hlp in your NLS\ENGLISH directory.
$ErrCode = $Buf->LastErr();

List

Query for the subordiantes of $ObjectName (typically a O or OU). $Buf will receive all objects. They can be retrieved with GetObjectName() & GetAttrVal(). See also Examples/Browse.pl
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Returns a number (not -1) if more iterations are needed. You may want to make the buffer larger if a lot of iterations are needed.
Returns -1 when no more iterations are needed.
Example:
$Iter = $Buf->List($ContextHandle, $ObjectName, $Iter);
$Iter = $Buf->List($ContextHandle, 'foo.bar.acme', $Iter);


ListPartions

Query for information about the replicas of partitions stored on the specified server. Use GetServerName() and GetPartitionInfo() to extract information retrieved.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Returns a number (not -1) if more iterations are needed.
Returns -1 when no more iterations are needed.
Example:
$Iter = $Buf->List($ContextHandle, $Iter, $ServerName);

ModifyObject

Execute a modify object operation on the object named in $ObjName. If iterations are needed the handle is returned in $Iter. See also Examples/ChangeAttr.pl
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Returns a number (not -1) if more iterations are needed to get all values. You may want to make the buffer larger if a lot of iterations are needed.
Returns -1 when no more iterations are needed.
$Iter = $Buf->ModifyObject($ContextHandle, $ObjName, $Iter, $more);

 

OpenStream

This method open a SYN_STREAM attribute (login-scripts and other custom stream attributes), and associates a file handle with it. The $flag value determines if the file is to opened in read only or write only. ``r'' or ``w''. Returns a filehandle that can be used in normal file operations if successful, undef if not.
NB! Remember to call $FilHandle->truncate(builtin perl method) after you're done writing. If you don't some 'old' lines may be included. You can not move around in the file. If you want to change a script you must read the script, change the lines you want and then write the entire script back.
Returns undef on error, in which case you can use LastErr() to get the netware error-code.
Example:
$FileHandle = $Buf->OpenStream($ContextHandle, $ObjectName, $AttrName, $flag);
@Script = <$FileHandle>;

PutAttrName

Put the attribute name of the attribute to delete, modify, add. PutAttrName() and PutAttrVal() is always used in pairs.
See also Examples/ChangeAttr.pl
Returns 0 on success, Netware error code on failure.
Example:
$ErrCode = $Buf->PutAttrName($ContextHandle, $AttrName);
$ErrCode = $Buf->PutAttrVal($ContextHandle, $SyntaxName, $Data);

PutAttrVal

Insert the value of a attribute to delete, modify, add ....
PutAttrName() and PutAttrVal() is always used in pairs.
This method require that you understand what's outlined in ndstypes.htmlincluded with this package. Examples are included in the Examples/ directory. You unziped with -d didn't you?
Returns 0 on success, Netware error code on failure.
Example:
$ErrCode = $Buf->PutAttrName($ContextHandle, $AttrName);
$ErrCode = $Buf->PutAttrVal($ContextHandle, $SyntaxName, $Data);

PutChange

Tells the buffer that a change is to be made on a given attribute ($AttributeName). $OperationName is one of: ``DS_OVERWRITE_VALUE'', ``DS_REMOVE_VALUE'', ``DS_ADD_VALUE''. See also Examples/ChangeAttr.pl
Returns 0 on success, Netware error code on failure.
Example:
$Buf->PutChange($ContextHandle, $OperationName, $AttributeName);

Read

Read data from NDS.
You get $ContextHandle from a PerlWare or NDSContext object.
$ObjectName is the object to read attributes from.
$InfoType is the information desired:
DS_ATTRIBUTE_NAMES
DS_ATTRIBUTE_VALUES
DS_EFFECTIVE_PRIVILEGES
Set $AllAttrs to 1 if you want all attributes or 0 for attributes previously put in $Buf.
$Iter is used to iterate if needed, $iter is -1 when no more iterations are needed.
$ResultBuf is a PerlWare::Buf_T object which will receive the values requested. Space must be allocated in $ResultBuf before calling Read(). This can be the same as $Buf if you request all attributes. See Examples\UsrAttr.pl.
See also Examples/GetAttr.pl for more info.
Returns undef on failure.
Example:
$Iter = $Buf->Read($ContextHandle, $ObjectName, $InfoType, $AllAttrs, $Iter, $ResultBuf);

SEE ALSO

the NDSContext class

the Misc help file

the NWServer class

the PerlWare help file

the Audit class

http://www.ahs.hist.no/distr/PerlWare/


COPYRIGHT

  Copyright (c) Steinar Kleven 1997.
  All rights reserved.