NWSM_SCAN_CONTROL

Defines the characteristics and attributes of the data sets to scan for as well as the path information to return in conjunction with NWSM_SELECTION_LIST.

Syntax

  typedef struct 
  { 
     UINT16   bufferSize; 
     UINT16   scanControlSize; 
     UINT32   scanType; 
     UINT32   firstAccessDateAndTime; 
     UINT32   lastAccessDateAndTime; 
     UINT32   firstCreateDateAndTime; 
     UINT32   lastCreateDateAndTime; 
     UINT32   firstModifiedDateAndTime; 
     UINT32   lastModifiedDateAndTime; 
     UINT32   firstArchivedDateAndTime; 
     UINT32   lastArchivedDateAndTime; 
     UINT8    returnChildTerminalNodeNameOnly; 
     UINT8    parentsOnly; 
     UINT8    childrenOnly; 
     UINT8    createSkippedDataSetsFile; 
     UINT8    generateCRC; 
     UINT8    returnNFSHardLinksInDataSetName; 
     UINT8    reserved[6]; 
     UINT32   scanChildNameSpaceType; 
     UINT32   returnNameSpaceType; 
     UINT8    callScanFilter; 
     UINT16   otherInformationSize; 
     UINT8    otherInformation[otherInformationSize]; 
  } NWSM_SCAN_CONTROL;

Fields

bufferSize

Specifies the structure size (including memory allocated for otherInformation).

scanControlSize

Specifies the memory used by all the structure fields excluding bufferSize.

scanType

Specifies a bit map indicating the selected scan type options.

firstAccessDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

lastAccessDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

firstCreateDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

lastCreateDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

firstModifiedDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

lastModifiedDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

firstArchivedDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

lastArchivedDateAndTime

Specifies the DOS-packed date and time criteria to scan for.

returnChildTerminalNodeNameOnly

Specifies if only the name of the child will be returned by the scan:

TRUE Return only the name for a child and full path for a parent
FALSE Always return the full path for a child or parent

parentsOnly

Specifies if only parents will be scanned:

TRUE Scan only parents
FALSE Scan both parents and children

childrenOnly

Specifies if only children will be scanned:

TRUE Scan only children
FALSE Scan both children and parents

createSkippedDataSetsFile

Specifies if the TSA will create a log of the data sets that qualified for the scan but were skipped:

TRUE Create a log file
FALSE Do not create a log file

generateCRC

Specifies if a CRC value will be generated for each data set:

TRUE Create a CRC value
FALSE Do not create a CRC value

returnNFSHardLinksINDataSetName

Specifies if the data set's NFS hard links will be returned in dataSetName:

TRUE dataSetName contains the returned NFS hard links
FALSE NFS hard links will not be returned

reserved

Is reserved for future use.

scanChildNameSpaceType

Specifies the name space of the child data sets to scan for-usually set to NWSM_ALL_NAME_SPACES (see Returned Name Space Type).

returnNameSpaceType

Specifies the name space types that the data set's name will be returned in.

callsScanFilter

Specifies if the TSA will use the specified scan filter:

TRUE Use the specified scan filter
FALSE Do not use the specified scan filter

otherInformationSize

Specifies the size of otherInformation.

otherInformation

Specifies developer-specific information.

Remarks

bufferSize may need to be larger than the structure because otherInformation may vary in size. To prevent the buffer size from being reallocated often, add extra space to bufferSize.

scanType is graphically represented by a 32-bitmap: bit 0-6 represents the predefined scan types and bit 7-31 represents the TSA specific scan types

Figure 4-1 Scan Type Bitmap

scanType bitmap

For Target Services that support purging deleted files, set scanType to NWSM_PURGE_IMMED_ON_DELETE before calling NWSMTSScanDataSetBegin.

The following table show the scan type that each TSA supports:

Value	Description
0x0001	NWSM_DO_NOT_TRAVERSE: Do not traverse the file system tree (see Scan Settings for more information).
0x0002	NWSM_EXCLUDE_ARCHIVED_CHILDREN: Do not scan for children data sets whose archive flag is set.
0x0004	NWSM_EXCLUDE_HIDDEN_CHILDREN: Do not scan for children data sets whose hidden flag is set.
0x0008	NWSM_EXCLUDE_HIDDEN_PARENTS: Do not scan for parent data sets whose hidden flag is set.
0x0010	NWSM_EXCLUDE_SYSTEM_CHILDREN: Do not scan for children data sets whose system flag is set.
0x0020	NWSM_EXCLUDE_SYSTEM_PARENTS: Do not scan for parent data sets whose system flag is set.
0x0040	NWSM_EXCLUDE_CHILD_TRUSTEES: Do not read the trustee information of children data sets.
0x0080	NWSM_EXCLUDE_PARENT_TRUSTEES: Do not read the trustee information of parent data sets.
0x0100	NWSM_EXCLUDE_ACCESS_DATABASE: Do not scan the database. For example, back up of server specific info from NetWare 4.x onwards.
0x0200	NWSM_EXCLUDE_VOLUME_RESTS: Do not read the resource restriction information.
0x0400	NWSM_EXCLUDE_DISK_SPACE_RESTS: Do not read the disk space restriction information.
0x0800	NWSM_EXCLUDE_EXTENDED_ATTRIBUTS: Do not read the extended attribute information.
0x1000	NWSM_EXCLUDE_DATA_STREAMS: Do not read a data set's data stream.
0x2000	NWSM_EXCLUDE_MIGRATED_CHILD: Do not read migrated data streams of children data sets. Read only the stub information for these migrated children.
0x4000	NWSM_EXPAND_COMPRESSED_DATA: Expand the data set before scanning it.
0x8000	NWSM_EXCLUDE_ARCH_CHILD_DATA: Do not scan the data of children that have been archived.
0x10000	NWSM_EXCLUDE_ARCH_CHILD_CHAR: Do not scan the child's characteristics if the child's characteristics archive bit is set.
0x20000	NWSM_FLAG_PURGE_IMMED_ON_DELETE: Set the data set's purge flag when it is deleted.
0x40000	NWSM_EXCLUDE_MIGRATED_FILES: Do not scan for children whose remote data access bit is set.
0x80000	NWSM_INCLUDE_PATH_COMPONENT: For each item in the include list, backup the individual parent components before processing the data sets.
0x100000	NWSM_EXCLUDE_HARDLINK_DATA : Do not backup the data for hardlinks except for the first encountered data node.
0X200000	NWSM_EXCLUDE_SECONDARY_DATA_STREAMS : Do not read a data set's secondary data stream.
0x400000	NNWSM_INCLUDE_SOFTLINK_CHILD : Reads the soft link along with real data of children data set's.
0X800000	NWSM_OR_DATE_TIME_FILTER: Backup the data, if the data sets date and time values are within the range specified in the date and time fields.

The TSA specifies which other scan types to enable and disable when a scan type is chosen. The TSA flags can be ORed to produce the desired action. However, the combination of various scan types can produce an illegal condition or unwanted results. The TSA will return an error indicating that an illegal condition might exist, but it cannot signal that an undesirable result might occur.

The date and time fields specify the range for the scan criteria. A data set meets the date and time criteria if all the data set's date and time values are within the range specified by all the date and time fields. Zero indicates an open-ended scan for that kind of date and time information (see Date and Time Fields for more information). These fields contain DOS-packed values and can be packed or unpacked by calling the "DOS Date and Time functions" shown in Storage Management Services Utilities Library. Some TSAs may not support all of the date and time fields (see NWSMTSGetUnsupportedOptions).

The following table gives an example of the scan type settings and indicates the results of each scan

firstAccessDateAndTime	lastAccessDateAndTime	Description
October 12, 1985 12:00:00	April 1, 1989 12:00:00	Returns information on all files accessed between October 12, 1985 12:00:00 and April 1, 1989 12:00:00 inclusively.
0	April 1, 1989 12:00:00	Returns information on all files accessed until and including April 1, 1989 12:00:00.
October 12, 1985 12:00:00	0	Returns information on all files accessed since October 12, 1985 12:00:00.
0	0	Returns information about all files.

TSA support for returnChildTerminalNodeNameOnly is indicated by calling NWSMTSGetUnsupportedOptions.

If returnChildTerminalNodeNameOnly is set to TRUE, NWSMTSScanDataSetBegin returns the fully qualified path of the parent of the first child data set found. For the name of the first child data set, call NWSMTSScanNextDataSet (the path information is provided by the parent).

childrenOnly must be set to false if returnChildTerminalNodeName is set to TRUE (see Scan Settings for more information).

TSA support for createSkippedDataSetsFile can be determined by calling NWSMTSGetUnsupportedOptions (see Log Files and NWSMTSScanDataSetBegin for more information).

generateCRC enhances data integrity, but decreases the TSA’s performance slightly if set to TRUE.

The values that can be set for returnNameSpaceType is listed in the following table.

Value	Description
0xFFFFFFFF	NWSM_ALL_NAME_SPACES: Return all the name spaces of the data set in Multi Byte Character Sets (MBCS) format.
0xFFFFFFFE	NWSM_TSA_DEFINED_RESOURCE_TYPE: Return the data set if it is a TSA defined resources.
0xFFFFFFFD	NWSM_CREATOR_NAME_SPACE: Return only the created name space of the data set in Multi Byte Character Sets (MBCS) format.
0xFFFFFFFC	NWSM_DIRECTORY_NAME_SPACE: Return the data set if it is a Directory Services data set.
0xFFFFFFFAL	NWSM_ALL_NAME_SPACES_UTF8: Return all the supported name spaces of the data set in UTF-8 format.
0xFFFFFFF9L	NWSM_CREATOR_NAME_SPACE_UTF8: Return only the created name space of the data set in UTF-8 format.
0xFFFFFFF8L	NWSM_ALL_NAME_SPACES_FORMATS: Return all the name spaces of the data set in all supported formats.
0x000	DOSNameSpace: Return only for DOS data set in MBCS format.
0x001	MACNameSpace: Return only for Mac data sets in MBCS format.
0x002	NFSNameSpace: Return only for NFS data sets in MBCS format.
0x003	FTAMNameSpace: Return only for FTAM data sets in MBCS format.
0x004	OS2NameSpace: Return only for OS/2 data sets in MBCS format.
0x100	DOSNameSpaceUtf8Type: Return only for DOS data sets in UTF-8 format
0x101	MACNameSpaceUtf8Type: Return only for Mac data sets in UTF-8 format
0x102	NFSNameSpaceUtf8Type: Return only for NFS data sets inUTF-8 format
0x104	LONGNameSpaceUtf8Type: Return only for LONG data sets in UTF-8 format

TSA defined resources are logical resource groupings. Logical groupings refers to the fact that a bindery or file server does not exist as a single entity but as a logical group of lesser resources. The bindery consists of 3 files while the file server consists of: the bindery, volume, directories, and files.

callScanFilter is not supported under NetWare 4.