Novell Doc: NDK: SMS Developer Components

Syntax

  #include <smstsapi.h> 
   
  CCODE NWSMTSWriteDataSet (
     UINT32      connection, 
     UINT32      dataSetHandle, 
     UINT32      bytesToWrite, 
     BUFFERPTR   buffer);

Parameters

connection: (IN) Specifies the connection information returned by NWSMTSConnectToTargetService or NWSMTSConnectToTargetServicEx.
dataSetHandle: (IN) Specifies the handle returned by NWSMTSOpenDataSetForRestore.
bytesToWrite: (IN) Specifies the number of bytes to write.
buffer: (IN) Points to the caller allocated buffer containing the data to be written back through the TSA. The contents of the buffer should have been obtained previously from the NWSMTSReadDataSet call during backup.

Return Values

See Section 9.3, Target Service Return Values for more information.

The following table lists the return values associated with the function.

0x00000000	Successful
0xFFFDFFAF	NWSMTS_CLUSTER_TARGET_DOES_NOT_EXIST
0xFFFDFFB5	NWSMTS_WRITE_ERROR
0xFFFDFFB6	NWSMTS_WRITE_ERROR_SHORT
0xFFFDFFB7	NWSMTS_WRITE_EA_ERROR
0xFFFDFFB8	NWSMTS_VALID_PARENT_HANDLE
0xFFFDFFB9	NWSMTS_UNSUPPORTED_FUNCTION
0xFFFDFFC4	NWSMTS_SCAN_ERROR
0xFFFDFFC6	NWSMTS_READ_ERROR
0xFFFDFFC8	NWSMTS_OVERFLOW
0xFFFDFFC9	NWSMTS_OUT_OF_MEMORY
0xFFFDFFCA	NWSMTS_OUT_OF_DISK_SPACE
0xFFFDFFCC	NWSMTS_OPEN_ERROR
0xFFFDFFDC	NWSMTS_INVALID_PATH
0xFFFDFFE5	NWSMTS_INVALID_DATA_SET_HANDLE
0xFFFDFFE6	NWSMTS_INVALID_DATA
0xFFFDFFE7	NWSMTS_INVALID_CONNECTION_HANDL
0xFFFDFFEC	NWSMTS_GET_ENTRY_INDEX_ERR
0xFFFDFFEF	NWSMTS_EXPECTING_TRAILER
0xFFFDFFF0	NWSMTS_EXPECTING_HEADER
0xFFFDFFF4	NWSMTS_DATA_SET_IS_OLDER
0xFFFDFFF5	NWSMTS_DATA_SET_IN_USE
0xFFFDFFF7	NWSMTS_DATA_SET_EXCLUDED
0xFFFDFFF8	NWSMTS_DATA_SET_ALREADY_EXISTS
0xFFFDFFF9	NWSMTS_CREATE_ERROR
0xFFFDFFFA	NWSMTS_CREATE_DIR_ENTRY_ERR
0xFFFDFFFB	NWSMTS_CLOSE_BINDERY_ERROR
0xFFFDFFFC	NWSMTS_CANT_ALLOT_DIR_HANDLE
0xFFFDFFFD	NWSMTS_BUFFER_UNDERFLOW
0xFFFDFFFF	NWSMTS_ACCESS_DENIED
0xFFFEFFFE	NWSMDR_INVALID_PARAMETER
0xFFFEFFFF	NWSMDR_INVALID_CONNECTION

Engine Developers

NWSMTSWriteDataSet deformats the data set data and writes it out to the Target Service. The FID functions described in Storage Management Services Utilities Library can be used to deformat the data set data.

Remarks

Before NWSMTSWriteDataSet is called, NWSMTSOpenDataSetForRestore must be called to open the data set.

NWSMTSWriteDataSet must be called repeatedly until all of the data is written to Target Services.

NWSMTSWriteDataSet writes the data set to the specified location. If the data spans many buffers, the engine will have to call NWSMTSWriteDataSet once for every buffer.

A special situation occurs when the restore mode is set to NWSM_DO_NOT_OVERWRITE_DATA_SET, and the data set spans multiple buffers. NWSMTSWriteDataSet must parse through the data to find the path information which may require sifting through multiple buffers. NWSMTSWriteDataSet can then determine if the data set exists on the Target Service.

NWSMTSWriteDataSet may not return NWSMTS_VALID_PARENT_HANDLE or NWSMTS_DATA_SET_ALREADY_EXISTS (indicating the data set exists) until it is called many times (see Invalid, Valid Handle).

NWSM_VALID_PARENT_HANDLE is returned when enough data has been received to create a valid parent handle and indicates that:

The parent already exists on the Target Service
The parent was not overwritten
A parent handle was created for the existing parent
The parent's children can be restored

If buffer contains fields that the TSA does not recognize, the fields are ignored.

NOTE:The bindery must be explicitly included in the restore session or it will not be restored.

Example

See NWSMTSOpenDataSetForRestore for an example.

NWSMTSWriteDataSet