═══ 1. Notices ═══ References in this publication to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. ═══ 1.1. Copyright notices ═══ (C) Copyright International Business Machines Corporation 1995, 1997. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 1.2. Trademarks ═══ For a list of IBM and non-IBM trademarks, refer to the online book Trademarks in the Information folder. ═══ 2. Starting the API server ═══ To start the API server, you must run the program PSNSD.EXE or double-click on its icon in the OS/2 Warp Server Backup/Restore folder. The syntax of the command is as follows: ┌──────────────────────┐  │ ──PSNSD─┬──────────────────────┼─── │ │ ├─/Pipe:─────┤ │ │ ├─/Port:──┤ │ │ └─/Port:───┘  is the name of a named pipe to listen on  is the name of a service which will be looked up in the TCP/IP services file to decide which port to listen on  is the number of a port to listen on The pipe name, service name or port number should be the same as that which will be passed to PsnsInit in the client which is going to connect to the server. As many named pipes or TCP/IP ports can be opened as are specified on the command line. If you specify /Pipe: without a pipe name, a default pipe name will be used. If you specify /Port: without a port name or service number, the service psnsapi will be looked up in the TCP/IP services file to find out which port to use. ═══ 3. OS/2 Warp Server Backup/Restore functions ═══ This section lists the functions available in the OS/2 Warp Server Backup/Restore C API.  Initialisation / termination functions - PsnsInit - PsnsTerm  Backup method functions - PsnsCreateBackupMethod - PsnsDeleteBackupMethod - PsnsRenameBackupMethod - PsnsCopyBackupMethod - PsnsBackupMethodInfo - PsnsListBackupMethods - PsnsEstimateBackupMethod - PsnsRunBackupMethod  Restore method functions - PsnsCreateRestoreMethod - PsnsDeleteRestoreMethod - PsnsRenameRestoreMethod - PsnsCopyRestoreMethod - PsnsRestoreMethodInfo - PsnsListRestoreMethods - PsnsEstimateRestoreMethod - PsnsRunRestoreMethod  Backup set functions - PsnsCreateBackupSet - PsnsDeleteBackupSet - PsnsBackupSetInfo - PsnsSetBackupSetConfig - PsnsGetBackupSetConfig - PsnsListBackupSets - PsnsTransferBackupSet - PsnsGetLogFile - PsnsEmptyBackupSet  Storage device functions - PsnsCreateStorageDevice - PsnsDeleteStorageDevice - PsnsStorageDeviceInfo - PsnsSetStorageDeviceConfig - PsnsGetStorageDeviceConfig - PsnsListStorageDevices - PsnsRefreshStorageDevices  Volume functions - PsnsCreateVolume - PsnsDeleteVolume - PsnsVolumeInfo - PsnsListVolumes - PsnsListVolumeBackupSets - PsnsActivateVolume - PsnsAssociateVolume  Schedule event functions - PsnsCreateEvent - PsnsDeleteEvent - PsnsCopyEvent - PsnsEventInfo - PsnsListEvents - PsnsGetNextEvent - PsnsActivateEvent  File filter functions - PsnsCreateFileFilter - PsnsDeleteFileFilter - PsnsRenameFileFilter - PsnsCopyFileFilter - PsnsFileFilterInfo - PsnsListFileFilters - PsnsAddFileFilterRule - PsnsDeleteFileFilterRule - PsnsFileFilterRuleInfo  Rulebook functions - PsnsCreateRulebook - PsnsDeleteRulebook - PsnsRenameRulebook - PsnsCopyRulebook - PsnsRulebookInfo - PsnsListRulebooks - PsnsAddRulebookRule - PsnsDeleteRulebookRule - PsnsRulebookRuleInfo  Source drive functions - PsnsListSourceDrives - PsnsSelectSourceDrive - PsnsRefreshSourceDrives - PsnsSourceDriveType  Settings and defaults - PsnsDefaults - PsnsSettings  File functions - PsnsListFiles - PsnsDropFiles - PsnsAddFile - PsnsBackupFiles - PsnsRestoreFiles - PsnsPurgeFiles  Utility functions - PsnsCloseList - PsnsMessageCallback - PsnsGetMessageText ═══ 3.1. PsnsActivateEvent ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsActivateEvent - Syntax ═══ /****************************************************/ /* This function activates or deactivates an event */ /* in the scheduler. */ /****************************************************/ int PsnsActivateEvent(PSNSHANDLE handle, USHORT eventID, BOOL activate); ═══ PsnsActivateEvent - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. eventID (USHORT) ID of the event to be activated or deactivated. activate (BOOL) TRUE Activate the event. FALSE Deactivate the event. ═══ PsnsActivateEvent - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_EVENT ═══ PsnsActivateEvent - Remarks ═══ Use this function to activate or deactivate an event in the OS/2 Warp Server Backup/Restore scheduler. When an event is deactivated, nothing will happen when the event's time is reached. This can be useful to temporarily stop a scheduled backup happening, for example, during a vacation or during system maintenance. ═══ PsnsActivateEvent - Related functions ═══  PsnsCreateEvent  PsnsDeleteEvent  PsnsCopyEvent  PsnsEventInfo  PsnsListEvents  PsnsGetNextEvent ═══ 3.2. PsnsActivateVolume ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsActivateVolume - Syntax ═══ /****************************************************/ /* This function marks a volume as active or */ /* inactive. */ /****************************************************/ int PsnsActivateVolume(PSNSHANDLE handle, ULONG volumeID, BOOL activate); ═══ PsnsActivateVolume - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. volumeID (ULONG) Volume ID of the volume to be activated or deactivated. activate (BOOL) Possible values: TRUE Activate the volume. FALSE Deactivate the volume. ═══ PsnsActivateVolume - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_VOLUME PSNS_FIXED_VOLUME PSNS_INDEX_DISKETTE PSNS_TRANSFERRED_OUT PSNS_IN_USE ═══ PsnsActivateVolume - Remarks ═══ Use this function to mark a volume as available or unavailable. When a volume is marked as unavailable (deactivated), OS/2 Warp Server Backup/Restore will not ask you for that volume when performing a backup. If you try to restore files from a backup set which contains deactivated volumes, you will see a warning message and files on the deactivated volumes will not be restored. ═══ PsnsActivateVolume - Related functions ═══  PsnsCreateVolume  PsnsDeleteVolume  PsnsVolumeInfo  PsnsListVolumes  PsnsListVolumeBackupSets  PsnsAssociateVolume ═══ 3.3. PsnsAddFile ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsAddFile - Syntax ═══ /****************************************************/ /* This function adds a file or group of files to */ /* the list of files to be backed up, restored or */ /* dropped manually. */ /****************************************************/ int PsnsAddFile(PSNSHANDLE handle, const char *filename, short reserved); ═══ PsnsAddFile - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. filename (const char *) Name of the file to add to the list. To add all files in a given directory to the list, append a backslash to the directory name. To add all files in a given directory, and all files in all subdirectories beneath that directory, use a filename such as C:\Project\*\. No other wildcards are allowed in the filename. reserved (short) Reserved, must be 0. ═══ PsnsAddFile - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_PATH ═══ PsnsAddFile - Remarks ═══ Use this function to add a file or group of files to the list of files to be backed up, restored, or dropped. When you have added all the necessary files to the list, they can be backed up using PsnsBackupFiles, restored using PsnsRestoreFiles, or dropped using PsnsDropFiles. If you choose to cancel the operation and not backup or restore the files, call PsnsPurgeFiles to empty the list without taking any other action. If there is a list of files which you commonly back up, you should consider using a backup method with a rulebook to back up the files instead of this function. ═══ PsnsAddFile - Related functions ═══  PsnsBackupFiles  PsnsDropFiles  PsnsRestoreFiles  PsnsPurgeFiles ═══ 3.4. PsnsAddFileFilterRule ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsAddFileFilterRule - Syntax ═══ /****************************************************/ /* This function adds a new rule to a file filter. */ /****************************************************/ int PsnsAddFileFilterRule(PSNSHANDLE handle, const char *fileFilter, PFILEFILTERRULE pFileFilterRule, int position); ═══ PsnsAddFileFilterRule - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. fileFilter (const char *) Name of the file filter to which the rule is to be added. pFileFilterRule (PFILEFILTERRULE) Pointer to a FILEFILTERRULE structure which details the rule which is to be added to the file filter. position (int) This specifies the position where the rule is to be added to the file filter; 1 means add at the beginning, 2 after the first rule and so on. ═══ PsnsAddFileFilterRule - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_INVALID_DRIVE PSNS_INVALID_PATH PSNS_INVALID_FILENAME PSNS_INVALID_POSITION ═══ PsnsAddFileFilterRule - Remarks ═══ Use this function to add a new rule to a file filter. The rules are applied in order, from first to last, to decide which files will be backed up. You can add the new rule in any position before the 'last' rule. ═══ PsnsAddFileFilterRule - Related functions ═══  PsnsDeleteFileFilterRule  PsnsFileFilterRuleInfo ═══ 3.5. PsnsAddRulebookRule ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsAddRulebookRule - Syntax ═══ /****************************************************/ /* This function adds a new rule to a rulebook. */ /****************************************************/ int PsnsAddRulebookRule(PSNSHANDLE handle, const char *rulebook, PRULEBOOKRULE pRulebookRule, int position); ═══ PsnsAddRulebookRule - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. rulebook (const char *) Name of the rulebook to which the rule is to be added. pRulebookRule (PRULEBOOKRULE) Pointer to a RULEBOOKRULE structure which details the rule which is to be added to the rulebook. position (int) This specifies the position where the rule is to be added to the rulebook; 1 means at the beginning, 2 after the first rule and so on. ═══ PsnsAddRulebookRule - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_INVALID_DRIVE PSNS_INVALID_PATH PSNS_INVALID_FILENAME PSNS_INVALID_POSITION ═══ PsnsAddRulebookRule - Remarks ═══ Use this function to add a new rule to a rulebook. The rules are applied in order, from first to last, to decide whether compression will be used and how many generations of individual files to keep. You can add the new rule in any position before the 'last' rule. ═══ PsnsAddRulebookRule - Related functions ═══  PsnsDeleteRulebookRule  PsnsRulebookRuleInfo ═══ 3.6. PsnsAssociateVolume ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsAssociateVolume - Syntax ═══ /****************************************************/ /* This function associates an existing volume with */ /* a backup set. */ /****************************************************/ int PsnsAssociateVolume(PSNSHANDLE handle, ULONG volumeID, const char *backupSet); ═══ PsnsAssociateVolume - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. volumeID (ULONG) ID of the volume to be associated with a backup set. backupSet (const char *) Name of the backup set with which to associate the volume. ═══ PsnsAssociateVolume - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_VOLUME PSNS_INVALID_BACKUP_SET PSNS_ALREADY_ASSOCIATED PSNS_INAPPROPRIATE_BACKUP_SET PSNS_IN_USE ═══ PsnsAssociateVolume - Remarks ═══ Use this function to associate a volume with a backup set. This means that when you perform a backup to the backup set, OS/2 Warp Server Backup/Restore will consider the volume when it is looking for a volume with free space to store backed-up data. This can be useful, for example, when scheduling an overnight backup to tape: you can create a new volume in advance and associate it with the backup set; then OS/2 Warp Server Backup/Restore can automatically use the new volume when it comes to do the backup, rather than prompting for a new volume. ═══ PsnsAssociateVolume - Related functions ═══  PsnsCreateVolume  PsnsDeleteVolume  PsnsVolumeInfo  PsnsListVolumes  PsnsListVolumeBackupSets  PsnsActivateVolume ═══ 3.7. PsnsBackupFiles ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsBackupFiles - Syntax ═══ /****************************************************/ /* This function backs up the list of files created */ /* by calls to PsnsAddFile. */ /****************************************************/ int PsnsBackupFiles(PSNSHANDLE handle, PBACKUPMETHODINFO pBackupMethodInfo, PSNSSTATSFN psnsStatsFn); ═══ PsnsBackupFiles - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pBackupMethodInfo (PBACKUPMETHODINFO) Pointer to a BACKUPMETHODINFO structure which contains settings which control how the backup method runs. The only fields in the structure which need to be set are:  backupSet  compression  generations  changedFilesOnly All other fields in the structure are ignored by this function. psnsStatsFn (PSNSSTATSFN) Pointer to a statistics callback function. This can be NULL. ═══ PsnsBackupFiles - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_INVALID_GENERATIONS PSNS_INVALID_COMPRESSION PSNS_TRANSFERRED_OUT PSNS_IN_USE ═══ PsnsBackupFiles - Remarks ═══ Use this function to back up a list of files. The callback function, if provided, is called whenever the statistics (number of files, folder and bytes backed up) have changed, or whenever there is a message which might interest the user. For more information on the statistics callback function, see PSNSSTATSFN. ═══ PsnsBackupFiles - Related functions ═══  PsnsAddFile  PsnsDropFiles  PsnsRestoreFiles  PsnsPurgeFiles ═══ 3.8. PsnsBackupMethodInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsBackupMethodInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a backup method. */ /****************************************************/ int PsnsBackupMethodInfo(PSNSHANDLE handle, const char *name, PBACKUPMETHODINFO pBackupMethodInfo, long mask); ═══ PsnsBackupMethodInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup method to be inspected or changed. pBackupMethodInfo (PBACKUPMETHODINFO) Pointer to a BACKUPMETHODINFO structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = BM_NONE. mask (long) Possible values: BM_NONE BM_DESCRIPTION BM_ALLFILES BM_DRIVE BM_DIRECTORY BM_SUBDIRECTORIES BM_COMPRESSION BM_GENERATIONS BM_USERULEBOOK BM_RULEBOOK BM_USEFILEFILTER BM_FILEFILTER BM_CHANGEDFILESONLY BM_PREVIEW BM_BACKUPSET BM_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = BM_ALL. ═══ PsnsBackupMethodInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_INVALID_DRIVE PSNS_INVALID_PATH PSNS_INVALID_MASK PSNS_INVALID_COMPRESSION PSNS_INVALID_GENERATIONS PSNS_INVALID_RULEBOOK PSNS_INVALID_FILE_FILTER PSNS_INVALID_BACKUP_SET ═══ PsnsBackupMethodInfo - Remarks ═══ Use this function to change a backup method or to inspect the current settings for a backup method. The mask parameter defines which settings are being changed. For more information on the individual fields, see BACKUPMETHODINFO. It is not possible to change the name of a backup method with this call; to do that, use PsnsRenameBackupMethod. ═══ PsnsBackupMethodInfo - Related functions ═══  PsnsCreateBackupMethod  PsnsDeleteBackupMethod  PsnsRenameBackupMethod  PsnsCopyBackupMethod  PsnsListBackupMethods  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.9. PsnsBackupSetInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsBackupSetInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a backup set. */ /****************************************************/ int PsnsBackupSetInfo(PSNSHANDLE handle, const char *name, PBACKUPSETINFO pBackupSetInfo, long mask); ═══ PsnsBackupSetInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be inspected or changed. pBackupSetInfo (PBACKUPSETINFO) Pointer to a BACKUPSETINFO structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = BS_NONE. mask (long) Possible values: BS_NONE BS_DESCRIPTION BS_ALL ═══ PsnsBackupSetInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_INVALID_MASK ═══ PsnsBackupSetInfo - Remarks ═══ Use this function to change a backup set or to inspect the current settings for a backup set. The mask parameter defines which settings are being changed. For more information on the individual fields, see BACKUPSETINFO. It is not possible to change which storage device a backup set uses; to do that, you must delete the backup set and create a new one. ═══ PsnsBackupSetInfo - Related functions ═══  PsnsCreateBackupSet  PsnsDeleteBackupSet  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsListBackupSets  PsnsTransferBackupSet  PsnsTransferIn  PsnsGetLogFile  PsnsEmptyBackupSet ═══ 3.10. PsnsCloseList ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCloseList - Syntax ═══ /****************************************************/ /* This function is used to terminate a listing */ /* operation before it has finished. */ /****************************************************/ int PsnsCloseList(PSNSHANDLE handle, PHPSNSLIST pHPsnsList); ═══ PsnsCloseList - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. ═══ PsnsCloseList - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE ═══ PsnsCloseList - Remarks ═══ Use this function to terminate a listing operation before it has finished. The OS/2 Warp Server Backup/Restore C API listing functions will automatically terminate when they have finished listing all of the objects which match the specified search criteria. However, sometimes it may be useful to stop listing objects before you have reached the last one, so use this function to free the list handle when you have finished with it. ═══ PsnsCloseList - Related functions ═══  PsnsListRestoreMethods  PsnsListBackupMethods  PsnsListBackupSets  PsnsListStorageDevices  PsnsListVolumes  PsnsListVolumeBackupSets  PsnsListEvents  PsnsListFileFilters  PsnsListRulebooks  PsnsListSourceDrives ═══ 3.11. PsnsCopyBackupMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCopyBackupMethod - Syntax ═══ /****************************************************/ /* This function creates a new backup method which */ /* is a copy of an existing backup method. */ /****************************************************/ int PsnsCopyBackupMethod(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsCopyBackupMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the existing backup method to be copied. newName (const char *) Name of the new backup method. ═══ PsnsCopyBackupMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_METHOD PSNS_INVALID_NAME PSNS_ALREADY_EXISTS ═══ PsnsCopyBackupMethod - Remarks ═══ Use this function to create a new backup method which is a copy of an existing one. newName must not be the same as the name of any existing backup method. ═══ PsnsCopyBackupMethod - Related functions ═══  PsnsCreateBackupMethod  PsnsDeleteBackupMethod  PsnsRenameBackupMethod  PsnsBackupMethodInfo  PsnsListBackupMethods  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.12. PsnsCopyEvent ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCopyEvent - Syntax ═══ /****************************************************/ /* This function creates a new event which is a */ /* copy of an existing event. */ /****************************************************/ int PsnsCopyEvent(PSNSHANDLE handle, USHORT eventID, USHORT *newEventID); ═══ PsnsCopyEvent - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. eventID (USHORT) ID of the existing event to be copied. newEventID (USHORT *) Pointer to where the new event ID will be stored. ═══ PsnsCopyEvent - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_EVENT ═══ PsnsCopyEvent - Remarks ═══ Use this function to create a new event which is a copy of an existing one. The ID of the newly-created event is returned in *newEventID. ═══ PsnsCopyEvent - Related functions ═══  PsnsCreateEvent  PsnsDeleteEvent  PsnsEventInfo  PsnsListEvents  PsnsGetNextEvent  PsnsActivateEvent ═══ 3.13. PsnsCopyFileFilter ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCopyFileFilter - Syntax ═══ /****************************************************/ /* This function creates a new file filter which is */ /* a copy of an existing file filter. */ /****************************************************/ int PsnsCopyFileFilter(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsCopyFileFilter - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the existing file filter to be copied. newName (const char *) Name of the new file filter. ═══ PsnsCopyFileFilter - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_ALREADY_EXISTS PSNS_INVALID_NAME ═══ PsnsCopyFileFilter - Remarks ═══ Use this function to create a new file filter which is a copy of an existing one. newName must not be the same as the name of any existing file filter. ═══ PsnsCopyFileFilter - Related functions ═══  PsnsCreateFileFilter  PsnsDeleteFileFilter  PsnsRenameFileFilter  PsnsFileFilterInfo  PsnsListFileFilters ═══ 3.14. PsnsCopyRestoreMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCopyRestoreMethod - Syntax ═══ /****************************************************/ /* This function creates a new restore method which */ /* is a copy of an existing restore method. */ /****************************************************/ int PsnsCopyRestoreMethod(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsCopyRestoreMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the existing restore method to be copied. newName (const char *) Name of the new restore method. ═══ PsnsCopyRestoreMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RESTORE_METHOD PSNS_ALREADY_EXISTS PSNS_INVALID_NAME ═══ PsnsCopyRestoreMethod - Remarks ═══ Use this function to create a new restore method which is a copy of an existing one. newName must not be the same as the name of any existing restore method. ═══ PsnsCopyRestoreMethod - Related functions ═══  PsnsCreateRestoreMethod  PsnsDeleteRestoreMethod  PsnsRenameRestoreMethod  PsnsRestoreMethodInfo  PsnsListRestoreMethods  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.15. PsnsCopyRulebook ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCopyRulebook - Syntax ═══ /****************************************************/ /* This function creates a new rulebook which is a */ /* copy of an existing rulebook. */ /****************************************************/ int PsnsCopyRulebook(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsCopyRulebook - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the existing rulebook to be copied. newName (const char *) Name of the new rulebook. ═══ PsnsCopyRulebook - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_ALREADY_EXISTS PSNS_INVALID_NAME ═══ PsnsCopyRulebook - Remarks ═══ Use this function to create a new rulebook which is a copy of an existing one. newName must not be the same as the name of any existing rulebook. ═══ PsnsCopyRulebook - Related functions ═══  PsnsCreateRulebook  PsnsDeleteRulebook  PsnsRenameRulebook  PsnsRulebookInfo  PsnsListRulebooks  PsnsAddRulebookRule  PsnsDeleteRulebookRule  PsnsRulebookRuleInfo ═══ 3.16. PsnsCreateBackupMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateBackupMethod - Syntax ═══ /****************************************************/ /* This function creates a new backup method. */ /****************************************************/ int PsnsCreateBackupMethod(PSNSHANDLE handle, const char *name); ═══ PsnsCreateBackupMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup method to be created. ═══ PsnsCreateBackupMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_ALREADY_EXISTS PSNS_INVALID_NAME ═══ PsnsCreateBackupMethod - Remarks ═══ Use this function to create a new backup method. name must not be the name of any existing backup method. The backup method is created with default settings; you can use PsnsBackupMethodInfo to change these. ═══ PsnsCreateBackupMethod - Related functions ═══  PsnsDeleteBackupMethod  PsnsRenameBackupMethod  PsnsCopyBackupMethod  PsnsBackupMethodInfo  PsnsListBackupMethods  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.17. PsnsCreateBackupSet ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateBackupSet - Syntax ═══ /****************************************************/ /* This function creates a new backup set. */ /****************************************************/ int PsnsCreateBackupSet(PSNSHANDLE handle, const char *name, const char *StorageDevice, const char *Config, const char *incStorageDevice, const char *incConfig); ═══ PsnsCreateBackupSet - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be created. StorageDevice (const char *) For a single device backup set this is the storage device the backup set will use for all backups, you should set the incStorageDevice and incConfig parameters to be NULL. For a dual device backup set this is the name of the storage device which this backup set will use for the base backup, you should also specify an incremental storage device. Config (const char *) Configuration string for the storage device; for more information see PsnsSetBackupSetConfig. For dual device backup sets this is the configuration string for the base storage device. incStorageDevice (const char *) Name of the storage device which this dual device backup set will use for incremental backups. When creating single device backup sets pass this parameter as NULL. incConfig (const char *) Configuration string for the incremental device; for more information see PsnsSetBackupSetConfig. When creating single device backup sets pass this parameter as NULL. ═══ PsnsCreateBackupSet - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_INVALID_STORAGE_DEVICE PSNS_CANNOT_CREATE_BACKUP_SET PSNS_INVALID_KEYWORD PSNS_INVALID_VALUE PSNS_SYNTAX_ERROR PSNS_INCOMPLETE_STRING PSNS_SEMANTIC_ERROR ═══ PsnsCreateBackupSet - Remarks ═══ Use this function to create a new backup set. name must not be the name of any existing backup set. The backup set is created with default settings; you can use PsnsBackupSetInfo to change these. When creating a normal, single storage device backup set just set the last two parameters to be NULL. When creating a dual storage device backup set specify all the parameters. ═══ PsnsCreateBackupSet - Related functions ═══  PsnsDeleteBackupSet  PsnsBackupSetInfo  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsListBackupSets  PsnsTransferBackupSet  PsnsTransferIn  PsnsGetLogFile  PsnsEmptyBackupSet ═══ 3.18. PsnsCreateEvent ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateEvent - Syntax ═══ /****************************************************/ /* This function creates a new scheduled event. */ /****************************************************/ int PsnsCreateEvent(PSNSHANDLE handle, EVENTTYPE type, const char *method, USHORT *eventID); ═══ PsnsCreateEvent - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. type (EVENTTYPE) Type of event to be created. method (const char *) Name of the backup method which the event will use. This can be changed later but must be specified when you first create an event. eventID (USHORT *) Pointer to where the ID of the new event should be stored. ═══ PsnsCreateEvent - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_EVENT_TYPE ═══ PsnsCreateEvent - Remarks ═══ Use this function to create a new scheduled event. The ID of the event is placed in *eventID. The event is created with default settings; you can use PsnsEventInfo to change these. ═══ PsnsCreateEvent - Related functions ═══  PsnsDeleteEvent  PsnsCopyEvent  PsnsEventInfo  PsnsListEvents  PsnsGetNextEvent  PsnsActivateEvent ═══ 3.19. PsnsCreateFileFilter ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateFileFilter - Syntax ═══ /****************************************************/ /* This function creates a new file filter. */ /****************************************************/ int PsnsCreateFileFilter(PSNSHANDLE handle, const char *name, FILEFILTERTYPE fileFilterType); ═══ PsnsCreateFileFilter - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the file filter to be created. fileFilterType (FILEFILTERTYPE) Type of file filter to create. ═══ PsnsCreateFileFilter - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_INVALID_FILE_FILTER_TYPE ═══ PsnsCreateFileFilter - Remarks ═══ Use this function to create a new file filter. name must not be the name of any existing file filter. The file filter is created empty; you can use PsnsFileFilterInfo to change its settings and PsnsAddFileFilterRule to add new rules to it. ═══ PsnsCreateFileFilter - Related functions ═══  PsnsDeleteFileFilter  PsnsRenameFileFilter  PsnsCopyFileFilter  PsnsFileFilterInfo  PsnsListFileFilters ═══ 3.20. PsnsCreateRestoreMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateRestoreMethod - Syntax ═══ /****************************************************/ /* This function creates a new restore method */ /****************************************************/ int PsnsCreateRestoreMethod(PSNSHANDLE handle, const char *name); ═══ PsnsCreateRestoreMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the restore method to be created. ═══ PsnsCreateRestoreMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_ALREADY_EXISTS PSNS_INVALID_NAME ═══ PsnsCreateRestoreMethod - Remarks ═══ Use this function to create a new restore method. name must not be the name of any existing restore method. The restore method is created with default settings; you can use PsnsRestoreMethodInfo to change these. ═══ PsnsCreateRestoreMethod - Related functions ═══  PsnsDeleteRestoreMethod  PsnsRenameRestoreMethod  PsnsCopyRestoreMethod  PsnsRestoreMethodInfo  PsnsListRestoreMethods  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.21. PsnsCreateRulebook ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateRulebook - Syntax ═══ /****************************************************/ /* This function creates a new rulebook. */ /****************************************************/ int PsnsCreateRulebook(PSNSHANDLE handle, const char *name); ═══ PsnsCreateRulebook - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the rulebook to be created. ═══ PsnsCreateRulebook - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_ALREADY_EXISTS PSNS_INVALID_NAME ═══ PsnsCreateRulebook - Remarks ═══ Use this function to create a new rulebook. name must not be the name of any existing rulebook. The rulebook is created empty; you can use PsnsRulebookInfo to change its settings and PsnsAddRulebookRule to add new rules to it. ═══ PsnsCreateRulebook - Related functions ═══  PsnsDeleteRulebook  PsnsRenameRulebook  PsnsCopyRulebook  PsnsRulebookInfo  PsnsListRulebooks  PsnsAddRulebookRule  PsnsDeleteRulebookRule  PsnsRulebookRuleInfo ═══ 3.22. PsnsCreateStorageDevice ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateStorageDevice - Syntax ═══ /****************************************************/ /* This function creates a new storage device. */ /****************************************************/ int PsnsCreateStorageDevice(PSNSHANDLE handle, const char *type, const char *config, char *name); ═══ PsnsCreateStorageDevice - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. type (const char *) Name of the storage device type you want to create. To find out what to put here, you should use PsnsListStorageDevices with the SD_CREATABLE mask bit set; this will list all the storage device types available for creating new storage devices. config (const char *) Configuration string for the storage device; for more information see PsnsSetStorageDeviceConfig. name (char *) Pointer to a buffer of length PSNS_NAME_SIZE + 1 to receive the name of the new storage device. ═══ PsnsCreateStorageDevice - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE_TYPE PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_INVALID_KEYWORD PSNS_INVALID_VALUE PSNS_SYNTAX_ERROR PSNS_INCOMPLETE_STRING PSNS_SEMANTIC_ERROR ═══ PsnsCreateStorageDevice - Remarks ═══ Use this function to create a new storage device. You need to specify what type of storage device is being created; to get a list of all the available storage device types for creating a new storage device, you should call PsnsListStorageDevices with the SD_CREATABLE mask bit set. The storage device is created with the default settings; to change them, use PsnsSetStorageDeviceConfig. ═══ PsnsCreateStorageDevice - Related functions ═══  PsnsDeleteStorageDevice  PsnsStorageDeviceInfo  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsListStorageDevices  PsnsRefreshStorageDevices ═══ 3.23. PsnsCreateVolume ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsCreateVolume - Syntax ═══ /****************************************************/ /* This function creates a new volume. */ /****************************************************/ int PsnsCreateVolume(PSNSHANDLE handle, const char *storageDevice, ULONG *volumeID); ═══ PsnsCreateVolume - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. storageDevice (const char *) Name of the storage device with which to create the volume. volumeID (ULONG *) Pointer to where the ID of the new volume should be stored. ═══ PsnsCreateVolume - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE PSNS_INVALID_STORAGE_DEVICE_TYPE PSNS_IN_USE ═══ PsnsCreateVolume - Remarks ═══ Use this function to create a new volume. The ID of the volume is placed in *volumeID. The volume will not be associated with any backup set and will not be used until you have called PsnsAssociateVolume to associate it with a backup set. ═══ PsnsCreateVolume - Related functions ═══  PsnsDeleteVolume  PsnsVolumeInfo  PsnsListVolumes  PsnsListVolumeBackupSets  PsnsActivateVolume  PsnsAssociateVolume ═══ 3.24. PsnsDefaults ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDefaults - Syntax ═══ /****************************************************/ /* This function gets or sets the default file */ /* filter, rulebook, backup set, compression and */ /* number of generations. */ /****************************************************/ int PsnsDefaults(PSNSHANDLE handle, PPSNSDEFAULTS pPsnsDefaults, long mask); ═══ PsnsDefaults - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pPsnsDefaults (PPSNSDEFAULTS) Pointer to a PSNSDEFAULTS structure which contains the new defaults if they are to be changed, and to receive the current defaults. If the corresponding bit in mask is set then the defaults will be changed to what is passed in this structure. The new defaults are returned in this structure. To get the defaults without changing them, set mask = SET_NONE. mask (long) Possible values: SET_NONE SET_FILEFILTER SET_RULEBOOK SET_BACKUPSET SET_COMPRESSION SET_GENERATIONS SET_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = SET_ALL. ═══ PsnsDefaults - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_INVALID_RULEBOOK PSNS_INVALID_COMPRESSION PSNS_INVALID_GENERATIONS ═══ PsnsDefaults - Remarks ═══ Use this function to inspect or change the default file filter, rulebook, backup set, compression and number of generations to be kept. The mask parameter defines which settings are changed. For more information on the individual fields, see PSNSDEFAULTS. ═══ PsnsDefaults - Related functions ═══  PsnsSettings ═══ 3.25. PsnsDeleteBackupMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteBackupMethod - Syntax ═══ /****************************************************/ /* This function deletes a backup method. */ /****************************************************/ int PsnsDeleteBackupMethod(PSNSHANDLE handle, const char *name); ═══ PsnsDeleteBackupMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup method to be deleted. ═══ PsnsDeleteBackupMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_METHOD PSNS_IN_USE ═══ PsnsDeleteBackupMethod - Remarks ═══ If the named backup method exists, it will be deleted. ═══ PsnsDeleteBackupMethod - Related functions ═══  PsnsCreateBackupMethod  PsnsRenameBackupMethod  PsnsCopyBackupMethod  PsnsBackupMethodInfo  PsnsListBackupMethods  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.26. PsnsDeleteBackupSet ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteBackupSet - Syntax ═══ /****************************************************/ /* This function deletes a backup set. */ /****************************************************/ int PsnsDeleteBackupSet(PSNSHANDLE handle, const char *name); ═══ PsnsDeleteBackupSet - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be deleted. ═══ PsnsDeleteBackupSet - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_IN_USE ═══ PsnsDeleteBackupSet - Remarks ═══ If the named backup set exists, it will be deleted. You should take care not to delete a backup set which is referenced by any backup methods or restore methods; if you do then they will become invalid. ═══ PsnsDeleteBackupSet - Related functions ═══  PsnsCreateBackupSet  PsnsBackupSetInfo  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsListBackupSets  PsnsTransferBackupSet  PsnsTransferIn  PsnsGetLogFile  PsnsEmptyBackupSet ═══ 3.27. PsnsDeleteEvent ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteEvent - Syntax ═══ /****************************************************/ /* This function deletes a scheduled event. */ /****************************************************/ int PsnsDeleteEvent(PSNSHANDLE handle, USHORT eventID); ═══ PsnsDeleteEvent - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. eventID (USHORT) ID of the event to be deleted. ═══ PsnsDeleteEvent - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_EVENT PSNS_IN_USE ═══ PsnsDeleteEvent - Remarks ═══ If an event exists with the given ID, it will be deleted. ═══ PsnsDeleteEvent - Related functions ═══  PsnsCreateEvent  PsnsCopyEvent  PsnsEventInfo  PsnsListEvents  PsnsGetNextEvent  PsnsActivateEvent ═══ 3.28. PsnsDeleteFileFilter ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteFileFilter - Syntax ═══ /****************************************************/ /* This function deletes a file filter. */ /****************************************************/ int PsnsDeleteFileFilter(PSNSHANDLE handle, const char *name); ═══ PsnsDeleteFileFilter - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the file filter to be deleted. ═══ PsnsDeleteFileFilter - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_IN_USE ═══ PsnsDeleteFileFilter - Remarks ═══ If the named file filter exists, it will be deleted. You should take care not to delete a file filter which is referenced by any backup methods; if you do then the backup methods will become invalid. ═══ PsnsDeleteFileFilter - Related functions ═══  PsnsCreateFileFilter  PsnsRenameFileFilter  PsnsCopyFileFilter  PsnsFileFilterInfo  PsnsListFileFilters ═══ 3.29. PsnsDeleteFileFilterRule ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteFileFilterRule - Syntax ═══ /****************************************************/ /* This function deletes a rule from a file filter. */ /****************************************************/ int PsnsDeleteFileFilterRule(PSNSHANDLE handle, const char *fileFilter, int which); ═══ PsnsDeleteFileFilterRule - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. fileFilter (const char *) Name of the file filter from which to delete a rule. which (int) Number of the rule to be deleted (the first rule is 1). ═══ PsnsDeleteFileFilterRule - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_INVALID_POSITION PSNS_IN_USE PSNS_READONLY ═══ PsnsDeleteFileFilterRule - Remarks ═══ Use this function to delete a rule from a file filter. ═══ PsnsDeleteFileFilterRule - Related functions ═══  PsnsAddFileFilterRule  PsnsFileFilterRuleInfo ═══ 3.30. PsnsDeleteRestoreMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteRestoreMethod - Syntax ═══ /****************************************************/ /* This function deletes a restore method. */ /****************************************************/ int PsnsDeleteRestoreMethod(PSNSHANDLE handle, const char *name); ═══ PsnsDeleteRestoreMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the restore method to be deleted. ═══ PsnsDeleteRestoreMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RESTORE_METHOD PSNS_IN_USE ═══ PsnsDeleteRestoreMethod - Remarks ═══ If the named restore method exists, it will be deleted. ═══ PsnsDeleteRestoreMethod - Related functions ═══  PsnsCreateRestoreMethod  PsnsDeleteRestoreMethod  PsnsRenameRestoreMethod  PsnsCopyRestoreMethod  PsnsRestoreMethodInfo  PsnsListRestoreMethods  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.31. PsnsDeleteRulebook ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteRulebook - Syntax ═══ /****************************************************/ /* This function deletes a rulebook. */ /****************************************************/ int PsnsDeleteRulebook(PSNSHANDLE handle, const char *name); ═══ PsnsDeleteRulebook - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the rulebook to be deleted. ═══ PsnsDeleteRulebook - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_IN_USE ═══ PsnsDeleteRulebook - Remarks ═══ If the named rulebook exists, it will be deleted. You should take care not to delete a rulebook which is referenced by any backup methods; if you do then the backup methods will become invalid. ═══ PsnsDeleteRulebook - Related functions ═══  PsnsCreateRulebook  PsnsRenameRulebook  PsnsCopyRulebook  PsnsRulebookInfo  PsnsListRulebooks ═══ 3.32. PsnsDeleteRulebookRule ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteRulebookRule - Syntax ═══ /****************************************************/ /* This function deletes a rule from a rulebook. */ /****************************************************/ int PsnsDeleteRulebookRule(PSNSHANDLE handle, const char *rulebook, int which); ═══ PsnsDeleteRulebookRule - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. rulebook (const char *) Name of the rulebook from which to delete a rule. which (int) Number of the rule to be deleted, (the first rule is 1). ═══ PsnsDeleteRulebookRule - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_INVALID_POSITION PSNS_IN_USE ═══ PsnsDeleteRulebookRule - Remarks ═══ Use this function to delete a rule from a rulebook. ═══ PsnsDeleteRulebookRule - Related functions ═══  PsnsAddRulebookRule  PsnsRulebookRuleInfo ═══ 3.33. PsnsDeleteStorageDevice ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteStorageDevice - Syntax ═══ /****************************************************/ /* This function deletes a storage device. */ /****************************************************/ int PsnsDeleteStorageDevice(PSNSHANDLE handle, const char *name); ═══ PsnsDeleteStorageDevice - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the storage device to be deleted. ═══ PsnsDeleteStorageDevice - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE PSNS_IN_USE PSNS_CANNOT_DELETE ═══ PsnsDeleteStorageDevice - Remarks ═══ Use this function to delete a storage device. Some storage devices cannot be deleted; you also cannot delete a storage device which has any backup sets associated with it. ═══ PsnsDeleteStorageDevice - Related functions ═══  PsnsCreateStorageDevice  PsnsStorageDeviceInfo  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsListStorageDevices  PsnsRefreshStorageDevices ═══ 3.34. PsnsDeleteVolume ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDeleteVolume - Syntax ═══ /****************************************************/ /* This function deletes a volume. */ /****************************************************/ int PsnsDeleteVolume(PSNSHANDLE handle, ULONG volumeID); ═══ PsnsDeleteVolume - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. volumeID (ULONG) ID of the volume to be deleted. ═══ PsnsDeleteVolume - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_VOLUME PSNS_IN_USE PSNS_CANNOT_DELETE PSNS_FIXED_VOLUME ═══ PsnsDeleteVolume - Remarks ═══ Use this function to delete a volume. Any data backed up to the volume will be lost. Fixed volumes (such as local fixed disks) cannot be deleted. ═══ PsnsDeleteVolume - Related functions ═══  PsnsCreateVolume  PsnsVolumeInfo  PsnsListVolumes  PsnsListVolumeBackupSets  PsnsActivateVolume  PsnsAssociateVolume ═══ 3.35. PsnsDropFiles ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsDropFiles - Syntax ═══ /****************************************************/ /* This function removes backed-up data for a list */ /* of files from a backup set. */ /****************************************************/ int PsnsDropFiles(PSNSHANDLE handle, const char *backupSet PSNSSTATSFN psnsStatsFn); ═══ PsnsDropFiles - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. backupSet (const char *) Name of the backup set from which to drop file(s). psnsStatsFn (PSNSSTATSFN) Pointer to a statistics callback function. This can be NULL. ═══ PsnsDropFiles - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_FILE_NOT_FOUND PSNS_ARCHIVE_ERROR PSNS_TRANSFERRED_OUT ═══ PsnsDropFiles - Remarks ═══ Use this function to remove information about a list of files from a backup set. After this, you will no longer be able to restore the generation(s) of the file(s) you have dropped. OS/2 Warp Server Backup/Restore will be able to reuse the space on the volume(s) taken up by these files. Before calling this function, you should list the files and generations you want to drop by calling PsnsAddFile. ═══ PsnsDropFiles - Related functions ═══  PsnsListFiles  PsnsAddFile  PsnsPurgeFiles ═══ 3.36. PsnsEmptyBackupSet ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsEmptyBackupSet - Syntax ═══ /****************************************************/ /* This function destroys all backed-up data in a */ /* backup set. */ /****************************************************/ int PsnsEmptyBackupSet(PSNSHANDLE handle, const char *name); ═══ PsnsEmptyBackupSet - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be emptied. ═══ PsnsEmptyBackupSet - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_IN_USE PSNS_ARCHIVE_ERROR PSNS_TRANSFERRED_OUT ═══ PsnsEmptyBackupSet - Remarks ═══ Use this function to destroy all backed-up data in a backup set. You will no longer be able to restore any of the files backed up to this backup set and OS/2 Warp Server Backup/Restore will be able to reuse the volumes which the backup set uses. The backup set itself is not deleted. ═══ PsnsEmptyBackupSet - Related functions ═══  PsnsCreateBackupSet  PsnsDeleteBackupSet  PsnsBackupSetInfo  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsListBackupSets  PsnsTransferBackupSet  PsnsTransferIn  PsnsGetLogFile  PsnsDeleteVolume ═══ 3.37. PsnsEstimateBackupMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsEstimateBackupMethod - Syntax ═══ /****************************************************/ /* This function counts the files and folders which */ /* would be backed up by a given backup method and */ /* calculates the estimated time for the backup. */ /****************************************************/ int PsnsEstimateBackupMethod(PSNSHANDLE handle, const char *name, PESTIMATE pEstimate); ═══ PsnsEstimateBackupMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup method to be estimated. pEstimate (PESTIMATE) Pointer to an ESTIMATE structure to receive the information. ═══ PsnsEstimateBackupMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_METHOD ═══ PsnsEstimateBackupMethod - Remarks ═══ Use this function to scan for files and folders which would be backed up by a backup method, and estimate how long the backup would take. OS/2 Warp Server Backup/Restore calculates the estimated time based on past backups to the same storage device. ═══ PsnsEstimateBackupMethod - Related functions ═══  PsnsRunBackupMethod ═══ 3.38. PsnsEstimateRestoreMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsEstimateRestoreMethod - Syntax ═══ /****************************************************/ /* This function counts the files and folders which */ /* would be restored by a given restore method. */ /****************************************************/ int PsnsEstimateRestoreMethod(PSNSHANDLE handle, const char *name, PESTIMATE pEstimate); ═══ PsnsEstimateRestoreMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the restore method to be estimated. pEstimate (PESTIMATE) Pointer to an ESTIMATE structure to receive the information. ═══ PsnsEstimateRestoreMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RESTORE_METHOD PSNS_ARCHIVE_ERROR ═══ PsnsEstimateRestoreMethod - Remarks ═══ Use this function to scan for files and folders which would be restored by a restore method. ═══ PsnsEstimateRestoreMethod - Related functions ═══  PsnsRunRestoreMethod ═══ 3.39. PsnsEventInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsEventInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a scheduled event. */ /****************************************************/ int PsnsEventInfo(PSNSHANDLE handle, USHORT eventID, PEVENTINFO pEventInfo, long mask); ═══ PsnsEventInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. eventID (USHORT) ID of the event to be inspected or changed. pEventInfo (PEVENTINFO) Pointer to an EVENTINFO structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = EV_NONE. mask (long) Possible values: EV_NONE EV_BACKUPMETHOD EV_HOURS EV_MINUTES EV_DAY EV_DAYS EV_WEEKS EV_CHANGEDFILESONLY EV_SHOWPREVIEW EV_ACTIVE EV_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = EV_ALL. ═══ PsnsEventInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_EVENT PSNS_IN_USE PSNS_INVALID_BACKUP_METHOD PSNS_INVALID_TIME PSNS_INVALID_MASK ═══ PsnsEventInfo - Remarks ═══ Use this function to change an event or to inspect the current settings for an event. The mask parameter defines which settings are being changed. For more information on the individual fields, see EVENTINFO. It is not possible to change the type of an event with this call; you must delete the event and create a new one. ═══ PsnsEventInfo - Related functions ═══  PsnsCreateEvent  PsnsDeleteEvent  PsnsCopyEvent  PsnsListEvents  PsnsGetNextEvent  PsnsActivateEvent ═══ 3.40. PsnsFileFilterInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsFileFilterInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a file filter. */ /****************************************************/ int PsnsFileFilterInfo(PSNSHANDLE handle, const char *name, PFILEFILTERINFO pFileFilterInfo, long mask); ═══ PsnsFileFilterInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the file filter to be inspected or changed. pFileFilterInfo (PFILEFILTERINFO) Pointer to a FILEFILTERINFO structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = FF_NONE. mask (long) Possible values: FF_NONE FF_TYPE FF_DESCRIPTION FF_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = FF_ALL. ═══ PsnsFileFilterInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_IN_USE PSNS_INVALID_FILE_FILTER_TYPE PSNS_INVALID_MASK ═══ PsnsFileFilterInfo - Remarks ═══ Use this function to change a file filter or to inspect the current settings for a file filter. The mask parameter defines which settings are being changed. For more information on the individual fields, see FILEFILTERINFO. It is not possible to change the name of a file filter with this call; to do that, use PsnsRenameFileFilter. ═══ PsnsFileFilterInfo - Related functions ═══  PsnsCreateFileFilter  PsnsDeleteFileFilter  PsnsRenameFileFilter  PsnsCopyFileFilter  PsnsListFileFilters  PsnsAddFileFilterRule  PsnsDeleteFileFilterRule  PsnsFileFilterRuleInfo ═══ 3.41. PsnsFileFilterRuleInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsFileFilterRuleInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a rule in a file filter. */ /****************************************************/ int PsnsFileFilterRuleInfo(PSNSHANDLE handle, const char *fileFilter, int which, PFILEFILTERRULE pFileFilterRule, long mask); ═══ PsnsFileFilterRuleInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. fileFilter (const char *) Name of the file filter to be inspected or changed. which (int) Number of the rule to be inspected or changed (the first rule is 1). pFileFilterRule (FILEFILTERRULE) Pointer to a FILEFILTERRULE structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = FF_NONE. mask (long) Possible values: FF_NONE FF_DRIVE FF_DIRECTORY FF_PATTERN FF_INCLUDE FF_SUBDIRECTORIES FF_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = FF_ALL. ═══ PsnsFileFilterRuleInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_IN_USE PSNS_INVALID_POSITION PSNS_INVALID_DRIVE PSNS_INVALID_PATH PSNS_INVALID_FILENAME PSNS_READONLY PSNS_INVALID_MASK ═══ PsnsFileFilterRuleInfo - Remarks ═══ Use this function to change a file filter rule or to inspect the current settings for a file filter rule. The mask parameter defines which settings are being changed. For more information on the individual fields, see FILEFILTERRULE. ═══ PsnsFileFilterRuleInfo - Related functions ═══  PsnsFileFilterInfo  PsnsAddFileFilterRule  PsnsDeleteFileFilterRule ═══ 3.42. PsnsGetBackupSetConfig ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsGetBackupSetConfig - Syntax ═══ /****************************************************/ /* This function gets the configuration information */ /* for a backup set. */ /****************************************************/ int PsnsGetBackupSetConfig(PSNSHANDLE handle, const char *name, char *config, PULONG length, char *incConfig, PULONG incLength); ═══ PsnsGetBackupSetConfig - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be inspected. config (char *) Pointer to a buffer to receive the configuration information, may be NULL. For dual device backup sets this is the configuration string for the base storage device. length (PULONG) If the config parameter is NULL this parameter may also be passed as NULL. Input Size of the buffer pointed to by config. Output Size of the buffer needed to contain the complete configuration string including the terminating NULL. incConfig (char *) For dual device backup sets this is a pointer to a buffer to receive the configuration information for the incremental storage device, may be NULL. For single device backup sets this parameter should be passed as NULL. incLength (PULONG) If the incConfig parameter is NULL this parameter may also be passed as NULL. Input Size of the buffer pointed to by incConfig. Output Size of the buffer needed to contain the complete configuration string including the terminating NULL. ═══ PsnsGetBackupSetConfig - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_TOO_MUCH_DATA PSNS_TRANSFERRED_OUT ═══ PsnsGetBackupSetConfig - Remarks ═══ Use this function to get the current configuration information for a backup set, or find out how large a buffer is needed to hold that information. The format of this information depends on the storage device which the backup set uses; to find out how all the standard OS/2 Warp Server Backup/Restore storage devices handle this, see Storage Device Configuration. ═══ PsnsGetBackupSetConfig - Related functions ═══  PsnsSetBackupSetConfig  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsTransferIn ═══ PsnsGetFileGeneration ═══ Select an item  Syntax  Parameters  Returns  Remarks  Related functions ═══ PsnsGetFileGeneration - Syntax ═══ /****************************************************/ /* This function gets information about one */ /* generation of a backed-up file. */ /****************************************************/ int PsnsGetFileGeneration(PSNSHANDLE handle, PPSNSFILEINFO pPsnsFileInfo); ═══ PsnsGetFileGeneration - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pPsnsFileInfo (PPSNSFILEINFO) Pointer to a PSNSFILEINFO structure into which the information will be put. The fields backupSet, filename and thisGeneration should be initialised to show which file, backup set and generation to get. ═══ PsnsGetFileGeneration - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_FILE_NOT_FOUND PSNS_INVALID_GENERATION PSNS_ARCHIVE_ERROR PSNS_TRANSFERRED_OUT ═══ PsnsGetFileGeneration - Remarks ═══ Use this function to get information about a specific generation of a backed-up file. This includes the date and time of backup, which volume the generation is stored on, and file system information about the file at the time it was backed up. You must first fill in the backupSet, filename and thisGeneration fields in the PSNSFILEINFO structure you pass to tell OS/2 Warp Server Backup/Restore which file and generation to retrieve information on. ═══ PsnsGetFileGeneration - Related functions ═══  PsnsListFiles ═══ 3.43. PsnsGetLastError ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsGetLastError - Syntax ═══ /****************************************************/ /* This function returns a text message associated */ /* with the last API function call. */ /****************************************************/ int PsnsGetLastError(PSNSHANDLE handle, char *message, PULONG length); ═══ PsnsGetLastError - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. message (char *) Buffer into which to put the message, may be NULL. length (PULONG) Input Size of the buffer pointed to by message. Output Size of the buffer needed to hold the entire message string, including the terminating NULL. ═══ PsnsGetLastError - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_TOO_MUCH_DATA ═══ PsnsGetLastError - Remarks ═══ Use this function to get a text message which describes the result of the last API function call, or the size of the buffer needed to hold the message. When an API call fails and returns a non-zero return code, use this function to get the error message which that function call produced. ═══ PsnsGetLastError - Related functions ═══  PsnsGetMessageText ═══ 3.44. PsnsGetLogFile ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsGetLogFile - Syntax ═══ /****************************************************/ /* This function returns the name of the log file */ /* for a backup set. */ /****************************************************/ int PsnsGetLogFile(PSNSHANDLE handle, const char *backupSet, char *buffer); ═══ PsnsGetLogFile - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. backupSet (const char *) Name of the backup set for which you want to get the log file. buffer (char *) Pointer to a buffer of length at least CCHMAXPATH to receive the filename of the log file for this backup set. ═══ PsnsGetLogFile - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET ═══ PsnsGetLogFile - Remarks ═══ Use this function to get the name of the log file for a backup set. If OS/2 Warp Server Backup/Restore is running locally, you will then be able to view, edit or delete the log file. ═══ PsnsGetLogFile - Related functions ═══  PsnsRunBackupMethod  PsnsRunRestoreMethod  PsnsTransferIn ═══ 3.45. PsnsGetMessageText ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsGetMessageText - Syntax ═══ /****************************************************/ /* This function returns a text message associated */ /* with an API return code. */ /****************************************************/ int PsnsGetMessageText(PSNSHANDLE handle, int rc, char *message, PULONG length); ═══ PsnsGetMessageText - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. rc (int) Return code for which you want to get a message. message (char *) Buffer into which to put the message, may by NULL. length (PULONG) Input Size of the buffer pointed to by message. Output Size of the buffer needed to hold the entire message string, including the terminating NULL. ═══ PsnsGetMessageText - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RC PSNS_TOO_MUCH_DATA ═══ PsnsGetMessageText - Remarks ═══ Use this function to retrieve a message which contains a textual description of an OS/2 Warp Server Backup/Restore API return code, or the size of the buffer needed to hold that description. ═══ PsnsGetMessageText - Related functions ═══  PsnsGetLastError ═══ 3.46. PsnsGetNextEvent ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsGetNextEvent - Syntax ═══ /****************************************************/ /* This function calculates which scheduled event */ /* is due to happen next, and returns information */ /* about it. */ /****************************************************/ int PsnsGetNextEvent(PSNSHANDLE handle, PEVENTINFO pEventInfo); ═══ PsnsGetNextEvent - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pEventInfo (PEVENTINFO) Pointer to an EVENTINFO structure to receive the event information. ═══ PsnsGetNextEvent - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_NO_EVENTS ═══ PsnsGetNextEvent - Remarks ═══ Use this function to find out which scheduled event is due to happen next. It is possible that no events are currently scheduled to happen; in that case, PSNS_NO_EVENTS will be returned. ═══ PsnsGetNextEvent - Related functions ═══  PsnsCreateEvent  PsnsDeleteEvent  PsnsCopyEvent  PsnsEventInfo  PsnsListEvents  PsnsActivateEvent ═══ 3.47. PsnsGetStorageDeviceConfig ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsGetStorageDeviceConfig - Syntax ═══ /****************************************************/ /* This function gets configuration information for */ /* a storage device. */ /****************************************************/ int PsnsGetStorageDeviceConfig(PSNSHANDLE handle, const char *name, char *config, PULONG length); ═══ PsnsGetStorageDeviceConfig - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the storage device to be inspected. config (char *) Pointer to a buffer to receive the configuration information, may be NULL. length (PULONG) Input Size of the buffer pointer to by config. Output Size of the buffer needed to contain the entire configuration string including a terminating NULL. ═══ PsnsGetStorageDeviceConfig - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE PSNS_TOO_MUCH_DATA ═══ PsnsGetStorageDeviceConfig - Remarks ═══ Use this function to get the current configuration information for a storage device, or find out how large a buffer is needed to hold this information. The format of this information depends on the storage device; to find out how all the standard OS/2 Warp Server Backup/Restore storage devices handle this, see Storage Device Configuration. ═══ PsnsGetStorageDeviceConfig - Related functions ═══  PsnsSetStorageDeviceConfig  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig ═══ 3.48. PsnsInit ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsInit - Syntax ═══ /****************************************************/ /* This function opens a connection to the API */ /* server for use with subsequent API functions. */ /****************************************************/ int PsnsInit(PSNSHANDLE *handle, PSNSCONNECTION psnsConnection, PVOID data); ═══ PsnsInit - Parameters ═══ handle (PSNSHANDLE *) Pointer to where the new handle should be stored. psnsConnection (PSNSCONNECTION) Possible values: PSNS_PIPE Connect using named pipes. PSNS_TCPIP Connect using TCP/IP sockets. data (PVOID) Pointer to data about the connection. To use named pipes, this should point to a PSNSPIPEINFO structure; if this structure is empty, a default pipe name will be used. To use TCP/IP, it should point to a string of the form "hostname:port" or "hostname:service" specifying either a port number or a service to be looked up in the TCP/IP services file; if the string is empty or NULL, the port will be decided by looking up psnsapi in the TCP/IP services file. ═══ PsnsInit - Returns ═══ PSNS_OK PSNS_COMMUNICATIONS_ERROR PSNS_NO_MORE_HANDLES PSNS_CANNOT_CONNECT ═══ PsnsInit - Remarks ═══ You must call this function before you can use any of the other OS/2 Warp Server Backup/Restore C API functions. This function opens a connection to the API server, which can be either local or remote. With one handle, you may only call one API function at a time. If you wish to have multiple threads which all use API functions, you must call PsnsInit again from each thread to get a new handle. When you have finished making API calls with the handle, call PsnsTerm. ═══ PsnsInit - Related functions ═══  PsnsTerm ═══ 3.49. PsnsListBackupMethods ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListBackupMethods - Syntax ═══ /****************************************************/ /* This function lists backup methods which match */ /* certain criteria. */ /****************************************************/ int PsnsListBackupMethods(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PBACKUPMETHODINFO pBackupMethodInfo, long mask); ═══ PsnsListBackupMethods - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pBackupMethodInfo (PBACKUPMETHODINFO) Pointer to a BACKUPMETHODINFO structure where the backup methods found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: BM_NONE BM_NAME BM_DESCRIPTION BM_ALLFILES BM_DRIVE BM_DIRECTORY BM_PATTERN BM_SUBDIRECTORIES BM_COMPRESSION BM_GENERATIONS BM_USERULEBOOK BM_RULEBOOK BM_USEFILEFILTER BM_FILEFILTER BM_CHANGEDFILESONLY BM_PREVIEW BM_BACKUPSET BM_ALL To search on more than one field, OR the different values together. To list all backup methods, use mask = BM_NONE. ═══ PsnsListBackupMethods - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES ═══ PsnsListBackupMethods - Remarks ═══ On the first call to PsnsListBackupMethods, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pBackupMethodInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first backup method which matches the search criteria is copied into the structure pointed to by pBackupMethodInfo. The name, description, fileFilter, rulebook and backupSet fields may all contain wildcards. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next backup method which matches the criteria is returned in the structure. When there are no more backup methods to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListBackupMethods - Related functions ═══  PsnsCreateBackupMethod  PsnsDeleteBackupMethod  PsnsRenameBackupMethod  PsnsCopyBackupMethod  PsnsBackupMethodInfo  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.50. PsnsListBackupSets ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListBackupSets - Syntax ═══ /****************************************************/ /* This function lists backup sets which match */ /* certain criteria. */ /****************************************************/ int PsnsListBackupSets(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PBACKUPSETINFO pBackupSetInfo, long mask); ═══ PsnsListBackupSets - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pBackupSetInfo (PBACKUPSETINFO) Pointer to a BACKUPSETINFO structure where the backup sets found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: BS_NONE BS_NAME BS_DESCRIPTION BS_STORAGEDEVICE BS_INCSTORAGEDEVICE BS_TRANSFERREDIN BS_ALL To search on more than one field, OR the different values together. To list all backup methods, use mask = BS_NONE. ═══ PsnsListBackupSets - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListBackupSets - Remarks ═══ On the first call to PsnsListBackupSets, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pBackupSetInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first backup set which matches the search criteria is copied into the structure pointed to by pBackupSetInfo. The name and description fields may contain wildcards. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next backup set which matches the criteria is returned in the structure. When there are no more backup sets to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListBackupSets - Related functions ═══  PsnsCreateBackupSet  PsnsDeleteBackupSet  PsnsBackupSetInfo  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsTransferBackupSet  PsnsTransferIn  PsnsGetLogFile  PsnsEmptyBackupSet ═══ 3.51. PsnsListEvents ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListEvents - Syntax ═══ /****************************************************/ /* This function lists scheduled events which match */ /* certain criteria. */ /****************************************************/ int PsnsListEvents(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PEVENTINFO pEventInfo, long mask); ═══ PsnsListEvents - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pEventInfo (PEVENTINFO) Pointer to an EVENTINFO structure where the events found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: EV_NONE EV_TYPE EV_BACKUPMETHOD EV_HOURS EV_MINUTES EV_DAY EV_DAYS EV_WEEKS EV_CHANGEDFILESONLY EV_SHOWPREVIEW EV_ACTIVE EV_LASTRUN_BEFORE EV_LASTRUN_AFTER EV_NEXTRUN_BEFORE EV_NEXTRUN_AFTER EV_ALL To search on more than one field, OR the different values together. To list all events, use mask = EV_NONE. ═══ PsnsListEvents - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListEvents - Remarks ═══ On the first call to PsnsListEvents, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pEventInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first event which matches the search criteria is copied into the structure pointed to by pEventInfo. The backupMethod field may contain wildcards. When searching for events based on the time of the last or next occurrence, you can search for times either before or after the specified time, by setting the appropriate bit in the mask (EV_LASTRUN_BEFORE or EV_LASTRUN_AFTER etc.). On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next event which matches the criteria is returned in the structure. When there are no more events to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListEvents - Related functions ═══  PsnsCreateEvent  PsnsDeleteEvent  PsnsCopyEvent  PsnsEventInfo  PsnsGetNextEvent  PsnsActivateEvent ═══ 3.52. PsnsListFileFilters ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListFileFilters - Syntax ═══ /****************************************************/ /* This function lists file filters which match */ /* certain criteria. */ /****************************************************/ int PsnsListFileFilters(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PFILEFILTERINFO pFileFilterInfo, long mask); ═══ PsnsListFileFilters - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pFileFilterInfo (PFILEFILTERINFO) Pointer to a FILEFILTERINFO structure where the file filters found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: FF_NONE FF_NAME FF_DESCRIPTION FF_SEARCHFILE FF_ALL To search on more than one field, OR the different values together. To list all file filters, use mask = FF_NONE. ═══ PsnsListFileFilters - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListFileFilters - Remarks ═══ On the first call to PsnsListFileFilters, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pFileFilterInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first file filter which matches the search criteria is copied into the structure pointed to by pFileFilterInfo. The name and description fields may both contain wildcards. You can also search for all file filters which match a particular file; put the name of the file in the searchFile field and set the FF_SEARCHFILE bit in the mask. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next file filter which matches the criteria is returned in the structure. When there are no more file filters to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListFileFilters - Related functions ═══  PsnsCreateFileFilter  PsnsDeleteFileFilter  PsnsRenameFileFilter  PsnsCopyFileFilter  PsnsFileFilterInfo ═══ 3.53. PsnsListFiles ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListFiles - Syntax ═══ /****************************************************/ /* This function lists files which have been backed */ /* up into a backup set, and which match certain */ /* criteria. */ /****************************************************/ int PsnsListFiles(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PPSNSFILEINFO pPsnsFileInfo, long mask); ═══ PsnsListFiles - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pPsnsFileInfo (PPSNSFILEINFO) Pointer to a PSNSFILEINFO structure where the files and generations found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: FILE_NONE FILE_FILENAME FILE_GENERATIONS_LESS FILE_GENERATIONS_MORE FILE_CREATIONDATE_BEFORE FILE_CREATIONDATE_ON FILE_CREATIONDATE_AFTER FILE_CREATIONTIME_BEFORE FILE_CREATIONTIME_AFTER FILE_WRITEDATE_BEFORE FILE_WRITEDATE_ON FILE_WRITEDATE_AFTER FILE_WRITETIME_BEFORE FILE_WRITETIME_AFTER FILE_BACKUPDATE_BEFORE FILE_BACKUPDATE_ON FILE_BACKUPDATE_AFTER FILE_BACKUPTIME_BEFORE FILE_BACKUPTIME_AFTER FILE_SIZE_LESS FILE_SIZE_MORE FILE_ATTRIBS_EXACT FILE_ATTRIBS_ALLOF FILE_ATTRIBS_SOMEOF FILE_ATTRIBS_NOTSOMEOF FILE_ATTRIBS_NONEOF FILE_VOLUMEID FILE_ALL FILE_ALLGENERATIONS To search on more than one field, OR the different values together. To list all files, use mask = FILE_NONE. ═══ PsnsListFiles - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK PSNS_INVALID_BACKUP_SET PSNS_ARCHIVE_ERROR PSNS_TRANSFERRED_OUT ═══ PsnsListFiles - Remarks ═══ Use this function to list files which have been backed up to a backup set. On the first call to PsnsListFiles, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pFiles and set the mask according to which fields you want to search on. The backupSet field must be set to the backup set you want to search in. On return from this call, the handle pointed to will have been set to a new list handle number, and the first file which matches the search criteria is copied into the structure pointed to by pPsnsFileInfo. The filename field may contain wildcards. When searching for files by date, you can search for dates before, on or after the specified date; when searching by time, you can search for times before or after the specified time. When searching by generations or file size, you can search for values greater or less than the specified value. When searching by attributes, you can search either for an exact match (FILE_ATTRIBS_EXACT), for files which have all of the specified attributes (FILE_ATTRIBS_ALLOF), for those which have some of the specified attributes (FILE_ATTRIBS_SOMEOF), for files which do not have some of the specified attributes (FILE_ATTRIBS_NOTSOMEOF, for example searching for files which are either not hidden or not read-only), or for files which have none of the specified attributes (FILE_ATTTRIBS_NONEOF). On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next file which matches the criteria is returned in the structure. When there are no more files to list, the handle is set back to 0 to indicate that the list has finished. Since any one file may have multiple generations backed up, this function will normally return information about the generation most relevant to your query. For simple matching queries, the most recent generation of the file which fits the criteria is returned. For queries of the 'less than', 'more than', 'before', 'after' types, the generation returned is the one which comes closest to the specified value while still fitting the criteria. For example, if you choose to list all files backed up before a certain date, then all files will be listed which have at least one generation backed up before that date, and the generation returned will be the one which was backed up most recently before that date. To list all generations of backed-up files which match your search criteria, set the FILE_ALLGENERATIONS bit in the mask. This will mean that all generations of files are returned, rather than just one generation of each file which matches. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListFiles - Related functions ═══  PsnsDropFiles ═══ 3.54. PsnsListRestoreMethods ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListRestoreMethods - Syntax ═══ /****************************************************/ /* This function lists restore methods which match */ /* certain criteria. */ /****************************************************/ int PsnsListRestoreMethods(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PRESTOREMETHODINFO pRestoreMethodInfo, long mask); ═══ PsnsListRestoreMethods - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pRestoreMethodInfo (PRESTOREMETHODINFO) Pointer to a RESTOREMETHODINFO structure where the restore methods found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: RM_NONE RM_NAME RM_DESCRIPTION RM_BACKUPSET RM_ALLFILES RM_DRIVE RM_DIRECTORY RM_PATTERN RM_SUBDIRECTORIES RM_BYDATE RM_PREVIEW RM_PROMPT RM_ORIGINALLOCATION RM_DESTINATIONDRIVE RM_DESTINATIONPATH To search on more than one field, OR the different values together. To list all backup methods, use mask = RM_NONE. ═══ PsnsListRestoreMethods - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListRestoreMethods - Remarks ═══ On the first call to PsnsListRestoreMethods, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pRestoreMethodInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first restore method which matches the search criteria is copied into the structure pointed to by pRestoreMethodInfo. The name, description and backupSet fields may all contain wildcards. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next restore method which matches the criteria is returned in the structure. When there are no more restore methods to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListRestoreMethods - Related functions ═══  PsnsCreateRestoreMethod  PsnsDeleteRestoreMethod  PsnsRenameRestoreMethod  PsnsCopyRestoreMethod  PsnsRestoreMethodInfo  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.55. PsnsListRulebooks ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListRulebooks - Syntax ═══ /****************************************************/ /* This function lists rulebooks which match */ /* certain criteria. */ /****************************************************/ int PsnsListRulebooks(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PRULEBOOKINFO pRulebookInfo, long mask); ═══ PsnsListRulebooks - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pRulebookInfo (PRULEBOOKINFO) Pointer to a RULEBOOKINFO structure where the rulebooks found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: RB_NONE RB_NAME RB_DESCRIPTION RB_ALL To search on more than one field, OR the different values together. To list all backup methods, use mask = RB_NONE. ═══ PsnsListRulebooks - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListRulebooks - Remarks ═══ On the first call to PsnsListRulebooks, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pRulebookInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first rulebook which matches the search criteria is copied into the structure pointed to by pRulebookInfo. The name and description fields may both contain wildcards. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next rulebook which matches the criteria is returned in the structure. When there are no more file filters to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListRulebooks - Related functions ═══  PsnsCreateRulebook  PsnsDeleteRulebook  PsnsRenameRulebook  PsnsCopyRulebook  PsnsRulebookInfo ═══ 3.56. PsnsListSourceDrives ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListSourceDrives - Syntax ═══ /****************************************************/ /* This function lists source drives which match */ /* certain criteria. */ /****************************************************/ int PsnsListSourceDrives(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PSOURCEDRIVEINFO pSourceDriveInfo, long mask); ═══ PsnsListSourceDrives - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pSourceDriveInfo (PSOURCEDRIVEINFO) Pointer to a SOURCEDRIVEINFO structure where the source drives found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: DR_NONE DR_LETTER DR_TYPE DR_SELECTED DR_ALL To search on more than one field, OR the different values together. To list all source drives, use mask = DR_NONE. ═══ PsnsListSourceDrives - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListSourceDrives - Remarks ═══ On the first call to PsnsListSourceDrives, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pSourceDriveInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first source drive which matches the search criteria is copied into the structure pointed to by pSourceDriveInfo. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next source drive which matches the criteria is returned in the structure. When there are no more source drives to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListSourceDrives - Related functions ═══  PsnsSelectSourceDrive  PsnsRefreshSourceDrives  PsnsSourceDriveType ═══ 3.57. PsnsListStorageDevices ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListStorageDevices - Syntax ═══ /****************************************************/ /* This function lists storage devices which match */ /* certain criteria. */ /****************************************************/ int PsnsListStorageDevices(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PSTORAGEDEVICEINFO pStorageDeviceInfo, long mask); ═══ PsnsListStorageDevices - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pStorageDeviceInfo (PSTORAGEDEVICEINFO) Pointer to a STORAGEDEVICEINFO structure where the storage devices found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: SD_NONE SD_NAME SD_DLLNAME SD_CREATABLE SD_ALL To search on more than one field, OR the different values together. To list all backup methods, use mask = SD_NONE. ═══ PsnsListStorageDevices - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListStorageDevices - Remarks ═══ On the first call to PsnsListStorageDevices, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pStorageDeviceInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first storage device which matches the search criteria is copied into the structure pointed to by pStorageDeviceInfo. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next storage device which matches the criteria is returned in the structure. When there are no more storage devices to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListStorageDevices - Related functions ═══  PsnsCreateStorageDevice  PsnsDeleteStorageDevice  PsnsStorageDeviceInfo  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsRefreshStorageDevices ═══ 3.58. PsnsListVolumeBackupSets ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListVolumeBackupSets - Syntax ═══ /****************************************************/ /* This function lists backup sets on a given */ /* volume. */ /****************************************************/ int PsnsListVolumeBackupSets(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, const char *storageDevice, PBACKUPSETVOLUME pBackupSetVolume); ═══ PsnsListVolumeBackupSets - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. storageDevice (const char *) (Optional) Name of the storage device on which to find the volume. pBackupSetVolume (PBACKUPSETVOLUME) Pointer to a BACKUPSETVOLUMEINFO structure where the backup sets found will be returned. ═══ PsnsListVolumeBackupSets - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK PSNS_INVALID_VOLUME ═══ PsnsListVolumeBackupSets - Remarks ═══ On the first call to PsnsListVolumeBackupSets, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should set the id field in *pBackupSetVolume to the ID of the volume for which you want to list backup sets. On return from this call, the handle pointed to will have been set to a new list handle number, and the first backup set on the volume is copied into the structure pointed to by pBackupSetVolume. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next backup set on the volume is returned in the structure. When there are no more backup sets to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. If the optional storageDevice parameter is filled in, then OS/2 Warp Server Backup/Restore will look at the volume in the storage device and generate a list of backup sets on the storage device. ═══ PsnsListVolumeBackupSets - Related functions ═══  PsnsVolumeInfo  PsnsListVolumes ═══ 3.59. PsnsListVolumes ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsListVolumes - Syntax ═══ /****************************************************/ /* This function lists volumes which match certain */ /* criteria. */ /****************************************************/ int PsnsListVolumes(PSNSHANDLE handle, PHPSNSLIST pHPsnsList, PVOLUMEINFO pVolumeInfo, long mask); ═══ PsnsListVolumes - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pHPsnsList (PHPSNSLIST) Pointer to a list handle. pVolumeInfo (PVOLUMEINFO) Pointer to a VOLUMEINFO structure where the volumes found will be returned. On the first call, this contains the criteria to search against. mask (long) Possible values: VOL_NONE VOL_NAME VOL_STORAGEDEVICE VOL_TRANSFERREDOUT VOL_AVAILABLE VOL_BACKUPSETS VOL_TOTALCAPACITY_LESS VOL_TOTALCAPACITY_MORE VOL_PSNSCAPACITY_LESS VOL_PSNSCAPACITY_MORE VOL_PSNSUSED_LESS VOL_PSNSUSED_MORE VOL_PSNSFREE_LESS VOL_PSNSFREE_MORE VOL_OTHERFREE_LESS VOL_OTHERFREE_MORE VOL_OTHERUSED_LESS VOL_OTHERUSED_MORE VOL_TOTALBAD_LESS VOL_TOTALBAD_MORE VOL_BACKUPSET VOL_INDEXNO VOL_ALL To search on more than one field, OR the different values together. To list all volumes, use mask = VOL_NONE. ═══ PsnsListVolumes - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_LIST_HANDLE PSNS_NO_MORE_HANDLES PSNS_INVALID_MASK ═══ PsnsListVolumes - Remarks ═══ On the first call to PsnsListVolumes, pHPsnsList should point to an HPSNSLIST which has been initialised to 0. You should pass the search criteria in pVolumeInfo and set the mask according to which fields you want to search on. On return from this call, the handle pointed to will have been set to a new list handle number, and the first volume which matches the search criteria is copied into the structure pointed to by pVolumeInfo. The name, storageDevice and backupSet fields may all contain wildcards. On subsequent calls, the handle pointed to is non-zero and both the initial contents of the structure and the mask are ignored; the next volume which matches the criteria is returned in the structure. When there are no more volumes to list, the handle is set back to 0 to indicate that the list has finished. If you want to interrupt the listing operation before getting to the last item, you should call PsnsCloseList to free the list handle. ═══ PsnsListVolumes - Related functions ═══  PsnsCreateVolume  PsnsDeleteVolume  PsnsVolumeInfo  PsnsListVolumeBackupSets  PsnsActivateVolume  PsnsAssociateVolume ═══ 3.60. PsnsMessageCallback ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsMessageCallback - Syntax ═══ /****************************************************/ /* This function registers a callback function for */ /* user messages. */ /****************************************************/ int PsnsMessageCallback(PSNSHANDLE handle, PSNSMESSAGEFN function, void *privates); ═══ PsnsMessageCallback - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. function (PSNSMESSAGEFN) Pointer to a callback function. privates (void *) This pointer will be passed to the callback function whenever it is called, so can be used to provide some sort of context information. ═══ PsnsMessageCallback - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE ═══ PsnsMessageCallback - Remarks ═══ Use this function to register a callback function for user messages. This will be called whenever there is a message which should be shown to the user or might require a response from the user. This function is called whenever a message box would appear if OS/2 Warp Server Backup/Restore were running in a graphical environment. For more information on the callback function, see PSNSMESSAGEFN. Note that the function does not necessarily have to involve the user; for example, when running unattended it might be more useful to simply log the message and return PSNSM_DEFAULT to take the default action. ═══ PsnsMessageCallback - Related functions ═══ ═══ 3.61. PsnsPurgeFiles ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsPurgeFiles - Syntax ═══ /****************************************************/ /* This function empties the list of files to be */ /* backed up or restored */ /****************************************************/ int PsnsPurgeFiles(PSNSHANDLE handle); ═══ PsnsPurgeFiles - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. ═══ PsnsPurgeFiles - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE ═══ PsnsPurgeFiles - Remarks ═══ Use this function to empty the list of files which you have created using PsnsAddFile. This means that you can start creating a new list of files to be backed up or restored. Note that this function does nothing to the files you have added to the list, it simply empties the list. ═══ PsnsPurgeFiles - Related functions ═══  PsnsAddFile  PsnsBackupFiles  PsnsRestoreFiles ═══ 3.62. PsnsRefreshSourceDrives ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRefreshSourceDrives - Syntax ═══ /****************************************************/ /* This function looks for drives on the system and */ /* refreshes the list of source drives. */ /****************************************************/ int PsnsRefreshSourceDrives(PSNSHANDLE handle); ═══ PsnsRefreshSourceDrives - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. ═══ PsnsRefreshSourceDrives - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE ═══ PsnsRefreshSourceDrives - Remarks ═══ Use this function to make OS/2 Warp Server Backup/Restore scan for drives and automatically refresh the list of source drives. This is automatically done every time OS/2 Warp Server Backup/Restore starts up. ═══ PsnsRefreshSourceDrives - Related functions ═══  PsnsListSourceDrives  PsnsSelectSourceDrive  PsnsSourceDriveType ═══ 3.63. PsnsRefreshStorageDevices ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRefreshStorageDevices - Syntax ═══ /****************************************************/ /* This function looks for locally attached storage */ /* devices and automatically adds them to the list */ /* of storage devices. */ /****************************************************/ int PsnsRefreshStorageDevices(PSNSHANDLE handle); ═══ PsnsRefreshStorageDevices - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. ═══ PsnsRefreshStorageDevices - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE ═══ PsnsRefreshStorageDevices - Remarks ═══ Use this function to make OS/2 Warp Server Backup/Restore scan for locally attached storage devices and add them to the list of storage devices. This happens automatically every time OS/2 Warp Server Backup/Restore starts up. ═══ PsnsRefreshStorageDevices - Related functions ═══  PsnsCreateStorageDevice  PsnsDeleteStorageDevice  PsnsStorageDeviceInfo  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsListStorageDevices ═══ 3.64. PsnsRenameBackupMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRenameBackupMethod - Syntax ═══ /****************************************************/ /* This function renames an existing backup method. */ /****************************************************/ int PsnsRenameBackupMethod(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsRenameBackupMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup method to be renamed. newName (const char *) New name for the backup method. ═══ PsnsRenameBackupMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_METHOD PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_IN_USE ═══ PsnsRenameBackupMethod - Remarks ═══ Use this function to rename a backup method. newName must not be the name of any existing backup method. ═══ PsnsRenameBackupMethod - Related functions ═══  PsnsCreateBackupMethod  PsnsDeleteBackupMethod  PsnsCopyBackupMethod  PsnsBackupMethodInfo  PsnsListBackupMethods  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.65. PsnsRenameFileFilter ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRenameFileFilter - Syntax ═══ /****************************************************/ /* This function renames an existing file filter. */ /****************************************************/ int PsnsRenameFileFilter(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsRenameFileFilter - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the file filter to be renamed. newName (const char *) New name for the file filter. ═══ PsnsRenameFileFilter - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_FILE_FILTER PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_IN_USE ═══ PsnsRenameFileFilter - Remarks ═══ Use this function to rename a file filter. newName must not be the name of any existing file filter. ═══ PsnsRenameFileFilter - Related functions ═══  PsnsCreateFileFilter  PsnsDeleteFileFilter  PsnsCopyFileFilter  PsnsFileFilterInfo  PsnsListFileFilters ═══ 3.66. PsnsRenameRestoreMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRenameRestoreMethod - Syntax ═══ /****************************************************/ /* This function renames an existing restore method */ /****************************************************/ int PsnsRenameRestoreMethod(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsRenameRestoreMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the restore method to be renamed. newName (const char *) New name for the restore method. ═══ PsnsRenameRestoreMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RESTORE_METHOD PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_IN_USE ═══ PsnsRenameRestoreMethod - Remarks ═══ Use this function to rename a restore method. newName must not be the name of any existing restore method. ═══ PsnsRenameRestoreMethod - Related functions ═══  PsnsCreateRestoreMethod  PsnsDeleteRestoreMethod  PsnsCopyRestoreMethod  PsnsRestoreMethodInfo  PsnsListRestoreMethods  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.67. PsnsRenameRulebook ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRenameRulebook - Syntax ═══ /****************************************************/ /* This function renames an existing rulebook. */ /****************************************************/ int PsnsRenameRulebook(PSNSHANDLE handle, const char *name, const char *newName); ═══ PsnsRenameRulebook - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the rulebook to be renamed. newName (const char *) New name for the rulebook. ═══ PsnsRenameRulebook - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_ALREADY_EXISTS PSNS_INVALID_NAME PSNS_IN_USE ═══ PsnsRenameRulebook - Remarks ═══ Use this function to rename a rulebook. newName must not be the name of any existing rulebook. ═══ PsnsRenameRulebook - Related functions ═══  PsnsCreateRulebook  PsnsDeleteRulebook  PsnsCopyRulebook  PsnsRulebookInfo  PsnsListRulebooks ═══ 3.68. PsnsRestoreFiles ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRestoreFiles - Syntax ═══ /****************************************************/ /* This function restores a list of files created */ /* by calls to PsnsAddFile. */ /****************************************************/ int PsnsRestoreFiles(PSNSHANDLE handle, PRESTOREMETHODINFO pRestoreMethodInfo, PSNSSTATSFN psnsStatsFn); ═══ PsnsRestoreFiles - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pRestoreMethodInfo (RESTOREMETHODINFO) Pointer to a RESTOREMETHODINFO structure that contains settings which control how the restore method runs. The only fields in the structure which need to be set are:  backupSet All other fields are ignored by this function. psnsStatsFn (PSNSSTATSFN) Pointer to a statistics callback function. This can be NULL. ═══ PsnsRestoreFiles - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_TRANSFERRED_OUT PSNS_IN_USE ═══ PsnsRestoreFiles - Remarks ═══ Use this function to restore a list of files. The callback function, if provided, is called whenever the statistics (number of files, folder and bytes restored) have changed, or whenever there is a message which might interest the user. For more information on the statistics callback function, see PSNSSTATSFN. ═══ PsnsRestoreFiles - Related functions ═══  PsnsAddFile  PsnsRestoreFiles  PsnsDropFiles  PsnsPurgeFiles ═══ 3.69. PsnsRestoreMethodInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRestoreMethodInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a restore method. */ /****************************************************/ int PsnsRestoreMethodInfo(PSNSHANDLE handle, const char *name, PRESTOREMETHODINFO pRestoreMethodInfo, long mask); ═══ PsnsRestoreMethodInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the restore method to be inspected or changed. pRestoreMethodInfo (PRESTOREMETHODINFO) Pointer to a RESTOREMETHODINFO structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = RM_NONE. mask (long) Possible values: RM_NONE RM_NAME RM_DESCRIPTION RM_BACKUPSET RM_ALLFILES RM_DRIVE RM_DIRECTORY RM_PATTERN RM_SUBDIRECTORIES RM_BYDATE RM_PREVIEW RM_PROMPT RM_ORIGINALLOCATION RM_DESTINATIONDRIVE RM_DESTINATIONPATH To set more than one setting, OR the different values together. To set all the settings, use mask = RM_ALL. ═══ PsnsRestoreMethodInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RESTORE_METHOD PSNS_INVALID_BACKUP_SET PSNS_INVALID_DRIVE PSNS_INVALID_PATH PSNS_INVALID_FILENAME PSNS_INVALID_MASK PSNS_IN_USE ═══ PsnsRestoreMethodInfo - Remarks ═══ Use this function to change a restore method or to inspect the current settings for a restore method. The mask parameter defines which settings are being changed. For more information on the individual fields, see RESTOREMETHODINFO. It is not possible to change the name of a restore method with this call; to do that, use PsnsRenameRestoreMethod. ═══ PsnsRestoreMethodInfo - Related functions ═══  PsnsCreateRestoreMethod  PsnsDeleteRestoreMethod  PsnsRenameRestoreMethod  PsnsCopyRestoreMethod  PsnsListRestoreMethods  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.70. PsnsRulebookInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRulebookInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a rulebook. */ /****************************************************/ int PsnsRulebookInfo(PSNSHANDLE handle, const char *name, PRULEBOOKINFO pRulebookInfo, long mask); ═══ PsnsRulebookInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the rulebook to be inspected or changed. pRulebookInfo (PRULEBOOKINFO) Pointer to a RULEBOOKINFO structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = RB_NONE. mask (long) Possible values: RB_NONE RB_DESCRIPTION RB_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = RB_ALL. ═══ PsnsRulebookInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_IN_USE PSNS_INVALID_MASK ═══ PsnsRulebookInfo - Remarks ═══ Use this function to change a rulebook or to inspect the current settings for a rulebook. The mask parameter defines which settings are being changed. For more information on the individual fields, see RULEBOOKINFO. It is not possible to change the name of a rulebook with this call; to do that, use PsnsRenameRulebook. ═══ PsnsRulebookInfo - Related functions ═══  PsnsCreateRulebook  PsnsDeleteRulebook  PsnsRenameRulebook  PsnsCopyRulebook  PsnsRulebookInfo  PsnsListRulebooks  PsnsAddRulebookRule  PsnsDeleteRulebookRule  PsnsRulebookRuleInfo ═══ 3.71. PsnsRulebookRuleInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRulebookRuleInfo - Syntax ═══ /****************************************************/ /* This function gets or sets all the information */ /* about a rule in a rulebook. */ /****************************************************/ int PsnsRulebookRuleInfo(PSNSHANDLE handle, const char *rulebook, int which, PRULEBOOKRULE pRulebookRule, long mask); ═══ PsnsRulebookRuleInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. rulebook (const char *) Name of the rulebook to be inspected or changed. which (int) Number of the rule to be inspected or changed (the first rule is 1). pRulebookRule (RULEBOOKRULE) Pointer to a RULEBOOKRULE structure which contains the new settings if they are to be changed, and to receive the current settings. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in this structure. To get the settings without changing them, set mask = RB_NONE. mask (long) Possible values: RB_NONE RB_DRIVE RB_DIRECTORY RB_PATTERN RB_GENERATIONS RB_COMPRESSION To set more than one setting, OR the different values together. To set all the settings, use mask = RB_ALL. ═══ PsnsRulebookRuleInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RULEBOOK PSNS_INVALID_POSITION PSNS_INVALID_DRIVE PSNS_INVALID_PATH PSNS_INVALID_FILENAME PSNS_INVALID_GENERATIONS PSNS_INVALID_COMPRESSION PSNS_IN_USE PSNS_INVALID_MASK PSNS_READONLY ═══ PsnsRulebookRuleInfo - Remarks ═══ Use this function to change a rulebook rule or to inspect the current settings for a rulebook rule. The mask parameter defines which settings are being changed. For more information on the individual fields, see RULEBOOKRULE. ═══ PsnsRulebookRuleInfo - Related functions ═══  PsnsRulebookInfo  PsnsAddRulebookRule  PsnsDeleteRulebookRule ═══ 3.72. PsnsRunBackupMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRunBackupMethod - Syntax ═══ /****************************************************/ /* This function runs a backup method. */ /****************************************************/ int PsnsRunBackupMethod(PSNSHANDLE handle, const char *name, PSNSSTATSFN psnsStatsFn); ═══ PsnsRunBackupMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup method to be run. psnsStatsFn (PSNSSTATSFN) Pointer to a statistics callback function. This can be NULL. ═══ PsnsRunBackupMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_METHOD PSNS_ARCHIVE_ERROR PSNS_IN_USE PSNS_TRANSFERRED_OUT ═══ PsnsRunBackupMethod - Remarks ═══ Use this function to run a backup method. The callback function, if provided, is called whenever the statistics (number of files, folder and bytes backed up) have changed, or whenever there is a message which might interest the user. For more information on the statistics callback function, see PSNSSTATSFN. ═══ PsnsRunBackupMethod - Related functions ═══  PsnsEstimateBackupMethod  PsnsEstimateRestoreMethod  PsnsRunRestoreMethod ═══ 3.73. PsnsRunRestoreMethod ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsRunRestoreMethod - Syntax ═══ /****************************************************/ /* This function runs a restore method. */ /****************************************************/ int PsnsRunRestoreMethod(PSNSHANDLE handle, const char *name, PSNSSTATSFN psnsStatsFn, BOOL base, BOOL incremental); ═══ PsnsRunRestoreMethod - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the restore method to be run. psnsStatsFn (PSNSSTATSFN) Pointer to a statistics callback function. This can be NULL. base (BOOL) This parameter is only used when running a restore method that references a dual device backup set. It is ignored for single device backup sets. TRUE Restore from the base storage device. FALSE Do not restore from the base storage device. incremental (BOOL) This parameter is only used when running a restore method that references a dual device backup set. It is ignored for single device backup sets. TRUE Restore from the incremental storage device. FALSE Do not restore from the incremental storage device. ═══ PsnsRunRestoreMethod - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_RESTORE_METHOD PSNS_IN_USE PSNS_ARCHIVE_ERROR PSNS_TRANSFERRED_OUT ═══ PsnsRunRestoreMethod - Remarks ═══ Use this function to run a restore method. The callback function, if provided, is called whenever the statistics (number of files, folder and bytes restored) have changed, or whenever there is a message which might interest the user. For more information on the statistics callback function, see PSNSSTATSFN. When restoring from a dual device backup set you must set at least one of the base and incremental parameters to be true. For single device backup sets these parameters are ignored. ═══ PsnsRunRestoreMethod - Related functions ═══  PsnsEstimateRestoreMethod  PsnsEstimateBackupMethod  PsnsRunBackupMethod ═══ 3.74. PsnsSelectSourceDrive ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsSelectSourceDrive - Syntax ═══ /****************************************************/ /* This function selects whether or not a source */ /* drive should be checked for files to back up. */ /****************************************************/ int PsnsSelectSourceDrive(PSNSHANDLE handle, char drive, BOOL use); ═══ PsnsSelectSourceDrive - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. drive (char) Drive letter to select or deselect. use (BOOL) TRUE Select this source drive for backup. FALSE Deselect this source drive for backup. ═══ PsnsSelectSourceDrive - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_SOURCE_DRIVE ═══ PsnsSelectSourceDrive - Remarks ═══ Use this function to tell OS/2 Warp Server Backup/Restore whether or not to check a source drive for files when performing a backup. For example, if you had a backup method to back up all program source files on your computer, you would probably want to check all local drives but not check any network drives you have attached. By default, local drives are selected and remote drives are not selected. ═══ PsnsSelectSourceDrive - Related functions ═══  PsnsListSourceDrives  PsnsRefreshSourceDrives  PsnsSourceDriveType ═══ 3.75. PsnsSetBackupSetConfig ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsSetBackupSetConfig - Syntax ═══ /****************************************************/ /* This function sets the configuration information */ /* for a backup set. */ /****************************************************/ int PsnsSetBackupSetConfig(PSNSHANDLE handle, const char *name, const char *config, const char *incConfig); ═══ PsnsSetBackupSetConfig - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be configured. config (const char *) Configuration string for the backup set. The format of this string depends on which storage device the backup set uses. For dual device backup sets this is the configuration string for the base backup set. incConfig (const char *) Configuration string for the incremental storage device of a dual device backup set. The format of this string depends on which incremental storage device the dual device backup set uses. For single device backup sets this parameter should be passed as NULL. ═══ PsnsSetBackupSetConfig - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_INVALID_CONFIGURATION PSNS_IN_USE PSNS_TRANSFERRED_OUT PSNS_INVALID_KEYWORD PSNS_INVALID_VALUE PSNS_SYNTAX_ERROR PSNS_INCOMPLETE_STRING PSNS_SEMANTIC_ERROR ═══ PsnsSetBackupSetConfig - Remarks ═══ Use this function to set the configuration information for a backup set. The format of this information depends on the storage device which the backup set uses; to find out how all the standard OS/2 Warp Server Backup/Restore storage devices handle this, see Storage Device Configuration. ═══ PsnsSetBackupSetConfig - Related functions ═══  PsnsGetBackupSetConfig  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsTransferIn ═══ 3.76. PsnsSetStorageDeviceConfig ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsSetStorageDeviceConfig - Syntax ═══ /****************************************************/ /* This function sets the configuration information */ /* for a storage device. */ /****************************************************/ int PsnsSetStorageDeviceConfig(PSNSHANDLE handle, const char *name, const char *config); ═══ PsnsSetStorageDeviceConfig - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the storage device to be configured. config (const char *) Configuration string for the storage device. The format of this string depends on the storage device type. ═══ PsnsSetStorageDeviceConfig - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE PSNS_INVALID_CONFIGURATION PSNS_IN_USE PSNS_NOT_CONFIGURABLE PSNS_INVALID_KEYWORD PSNS_INVALID_VALUE PSNS_SYNTAX_ERROR PSNS_INCOMPLETE_STRING PSNS_SEMANTIC_ERROR ═══ PsnsSetStorageDeviceConfig - Remarks ═══ Use this function to set the configuration information for a storage device. The only storage device currently changeable using this command is ADSM. The format of this information depends on the storage device; to find out how all the standard OS/2 Warp Server Backup/Restore storage devices handle this, see Storage Device Configuration. ═══ PsnsSetStorageDeviceConfig - Related functions ═══  PsnsGetStorageDeviceConfig  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig ═══ 3.77. PsnsSettings ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsSettings - Syntax ═══ /****************************************************/ /* This function gets or sets many of the general */ /* options. */ /****************************************************/ int PsnsSettings(PSNSHANDLE handle, PPSNSSETTINGS pPsnsSettings, long mask); ═══ PsnsSettings - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. pPsnsSettings (PPSNSSETTINGS) Pointer to a PSNSSETTINGS structure which contains the new settings, if they are to be changed. If the corresponding bit in mask is set then the settings will be changed to what is passed in this structure. The new settings are returned in the structure. To get the settings without changing them at all, set mask = SET_NONE. mask (long) Possible values: SET_NONE SET_MANUALPRIORITY SET_AUTOPRIORITY SET_TEMPPATH SET_FLAGS SET_LOGFILELIMIT SET_BACKUPEXIT SET_RESTOREEXIT SET_ACLENABLE SET_ACLFILENAME SET_ALL To set more than one setting, OR the different values together. To set all the settings, use mask = SET_ALL. ═══ PsnsSettings - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_PRIORITY PSNS_INVALID_PATH PSNS_INVALID_FLAGS PSNS_INVALID_MASK ═══ PsnsSettings - Remarks ═══ Use this function to change the following settings:  Priority of backup and restore threads  Path for temporary files  Log file options  User exits For more information on the individual options, see PSNSSETTINGS. ═══ PsnsSettings - Related functions ═══  PsnsDefaults ═══ 3.78. PsnsSourceDriveType ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsSourceDriveType - Syntax ═══ /****************************************************/ /* This function sets the type of a source drive. */ /****************************************************/ int PsnsSourceDriveType(PSNSHANDLE handle, char drive, DRIVETYPE driveType); ═══ PsnsSourceDriveType - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. drive (char) Drive letter of the source drive to be changed. driveType (DRIVETYPE) New type for the source drive. ═══ PsnsSourceDriveType - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_DRIVE_TYPE ═══ PsnsSourceDriveType - Remarks ═══ Use this function to tell OS/2 Warp Server Backup/Restore what type of drive a particular source drive is. Usually this should be detected automatically but this call allows you to override the automatic detection. ═══ PsnsSourceDriveType - Related functions ═══  PsnsListSourceDrives  PsnsSelectSourceDrive  PsnsRefreshSourceDrives ═══ 3.79. PsnsStorageDeviceInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsStorageDeviceInfo - Syntax ═══ /****************************************************/ /* This function gets all the information */ /* about a storage device. */ /****************************************************/ int PsnsStorageDeviceInfo(PSNSHANDLE handle, const char *name, PSTORAGEDEVICEINFO pStorageDevice, long mask); ═══ PsnsStorageDeviceInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the storage device to be inspected. pStorageDevice (PSTORAGEDEVICEINFO) Pointer to a STORAGEDEVICEINFO structure to receive the storage device information. mask (long) Reserved - must be SD_NONE. ═══ PsnsStorageDeviceInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE PSNS_INVALID_MASK PSNS_IN_USE ═══ PsnsStorageDeviceInfo - Remarks ═══ Use this function to get information about a storage device. Since there are currently no storage device settings which can be modified, the mask parameter is unused. For more information on the individual fields, see STORAGEDEVICEINFO. ═══ PsnsStorageDeviceInfo - Related functions ═══  PsnsCreateStorageDevice  PsnsDeleteStorageDevice  PsnsSetStorageDeviceConfig  PsnsGetStorageDeviceConfig  PsnsListStorageDevices  PsnsRefreshStorageDevices ═══ 3.80. PsnsTerm ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsTerm - Syntax ═══ /****************************************************/ /* This function terminates an API session and */ /* frees the API handle. */ /****************************************************/ int PsnsTerm(PSNSHANDLE handle); ═══ PsnsTerm - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. ═══ PsnsTerm - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE ═══ PsnsTerm - Remarks ═══ You should call this function whenever you have finished with a handle which was obtained using PsnsInit. ═══ PsnsTerm - Related functions ═══  PsnsInit ═══ 3.81. PsnsTransferBackupSet ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsTransferBackupSet - Syntax ═══ /****************************************************/ /* This function transfers a backup set in or out. */ /****************************************************/ int PsnsTransferBackupSet(PSNSHANDLE handle, const char *name, BOOL action, BOOL base); ═══ PsnsTransferBackupSet - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. name (const char *) Name of the backup set to be transferred in or out. action (BOOL) TRUE Transfer the backup set in. FALSE Transfer the backup set out. base (BOOL) This parameter is only used when transferring out a dual device backup set. It is ignored for single device backup sets and when transferring in. TRUE Transfer out to the base storage device. FALSE Transfer out to the incremental storage device. ═══ PsnsTransferBackupSet - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_BACKUP_SET PSNS_TRANSFERRED_OUT PSNS_TRANSFERRED_IN ═══ PsnsTransferBackupSet - Remarks ═══ Use this function to transfer out or transfer in a backup set. When a backup set is transferred out, you cannot use it for backing up or restoring, but you can take it to another computer and transfer it in to use the data on it. Transferring out ensures that all indexing information stored on the backup set media is up to date. ═══ PsnsTransferBackupSet - Related functions ═══  PsnsCreateBackupSet  PsnsDeleteBackupSet  PsnsBackupSetInfo  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsListBackupSets  PsnsTransferIn  PsnsGetLogFile  PsnsEmptyBackupSet ═══ 3.82. PsnsTransferIn ═══ Select an item  Syntax  Parameters  Returns  Remarks  Related functions ═══ PsnsTransferIn - Syntax ═══ /****************************************************/ /* This function transfers in a backup set from a */ /* storage device. */ /****************************************************/ int PsnsTransferIn(PSNSHANDLE handle, const char *storageDevice, const char *backupSet); ═══ PsnsTransferIn - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. storageDevice (const char *) Name of the storage device from which to transfer in. backupSet (const char *) Name of the backup set to transfer in. ═══ PsnsTransferIn - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_STORAGE_DEVICE PSNS_IN_USE ═══ PsnsTransferIn - Remarks ═══ Use this function to transfer in a backup set which OS/2 Warp Server Backup/Restore does not know about. This function reads all the indexing information off the backup set media and creates a new backup set which refers to it. ═══ PsnsTransferIn - Related functions ═══  PsnsCreateBackupSet  PsnsDeleteBackupSet  PsnsBackupSetInfo  PsnsSetBackupSetConfig  PsnsGetBackupSetConfig  PsnsListBackupSets  PsnsTransferBackupSet  PsnsGetLogFile  PsnsEmptyBackupSet ═══ 3.83. PsnsVolumeInfo ═══ Select an item  Syntax  Parameters  Returns  Remarks  Example  Related functions ═══ PsnsVolumeInfo - Syntax ═══ /****************************************************/ /* This function gets all the information about a */ /* volume. */ /****************************************************/ int PsnsVolumeInfo(PSNSHANDLE handle, ULONG volumeID, PVOLUMEINFO pVolumeInfo, long mask); ═══ PsnsVolumeInfo - Parameters ═══ handle (PSNSHANDLE) Handle returned by PsnsInit. volumeID (ULONG) ID of the volume to be inspected. pVolumeInfo (PVOLUMEINFO) Pointer to a VOLUMEINFO structure to receive the volume information. mask (long) Reserved - must be 0. ═══ PsnsVolumeInfo - Returns ═══ PSNS_OK PSNS_HANDLE_IN_USE PSNS_COMMUNICATIONS_ERROR PSNS_INVALID_HANDLE PSNS_INVALID_VOLUME PSNS_IN_USE PSNS_INVALID_MASK ═══ PsnsVolumeInfo - Remarks ═══ Use this function to get information about a volume. Since there are currently no volume settings which can be modified, the mask parameter is ignored. ═══ PsnsVolumeInfo - Related functions ═══  PsnsCreateVolume  PsnsDeleteVolume  PsnsListVolumes  PsnsListVolumeBackupSets  PsnsActivateVolume  PsnsAssociateVolume ═══ 4. Data types ═══ This section lists the data types defined by the OS/2 Warp Server Backup/Restore C API.  BACKUPMETHODINFO  BACKUPSETINFO  BACKUPSETVOLUME  DRIVETYPE  ESTIMATE  EVENTINFO  EVENTOPTION  EVENTTYPE  FILEFILTERINFO  FILEFILTERRULE  FILEFILTERTYPE  HPSNSLIST  PSNSCOMPRESSION  PSNSCONNECTION  PSNSDEFAULTS  PSNSFFB  PSNSFILEINFO  PSNSHANDLE  PSNSPIPEINFO  PSNSPRIORITY  PSNSSETTINGS  PSNSSTATSFN  RESTOREMETHODINFO  RULEBOOKINFO  RULEBOOKRULE  SOURCEDRIVEINFO  STORAGEDEVICEINFO  ULONG64  VOLUMEINFO ═══ 4.1. BACKUPMETHODINFO ═══ typedef struct { char name[PSNS_NAME_SIZE + 1]; char description[PSNS_DESCRIPTION_SIZE + 1]; BOOL allFiles; char drive; char directory[CCHMAXPATH]; BOOL subdirectories; PSNSCOMPRESSION compression; int generations; BOOL useRulebook; char rulebook[PSNS_NAME_SIZE + 1]; BOOL useFileFilter; char fileFilter[PSNS_NAME_SIZE + 1]; BOOL changedFilesOnly; BOOL preview; char backupSet[PSNS_NAME_SIZE + 1]; } BACKUPMETHODINFO, *PBACKUPMETHODINFO; name (char[]) Name of the backup method. description (char[]) Description of the backup method. allFiles (BOOL) TRUE Allow backup of any file; the drive, directory and subdirectories fields are ignored. FALSE Allow backup of files specified by the drive, directory and subdirectories fields. drive (char) Drive letter from which to back up files. An asterisk (*) means all drives. directory (char[]) Directory to from which to back up files. This may end in a an asterisk (*) to allow matching of more than one directory. subdirectories (BOOL) TRUE Include subdirectories of the specified directory. FALSE Do not include subdirectories. compression (PSNSCOMPRESSION) PSNS_NOCOMPRESSIONDon't compress data. PSNS_COMPRESSIONDo compress data. PSNS_DEFAULT Default compression. generations (int) Number of generations of backed up files to keep. useRulebook (BOOL) TRUE Use the rulebook named in rulebook The compression and generations fields are ignored. FALSE Do not use a rulebook; use the settings in compression and generations The rulebook field is ignored. rulebook (char[]) Name of the rulebook to use. If this is a zero-length string then the default rulebook is used. useFileFilter (BOOL) TRUE Use the file filter named in fileFilter to decide which files to back up. FALSE Back up all files in the selected directories. fileFilter is ignored. fileFilter (char[]) Name of the file filter to use. If this is a zero-length string then the default file filter is used. changedFilesOnly (BOOL) TRUE Only back up files which have changed since the last backup to this backup set. FALSE Back up all files, regardless of whether they have changed. preview (BOOL) TRUE Show a preview before the backup and allow the user to select or deselect individual files. FALSE Do not show a preview. Note: Showing a preview is only useful if the backup method is to be run from the OS/2 Warp Server Backup/Restore window; it is not possible to show a preview when running a backup method using the API. backupSet (char[]) Backup set into which back up data is to be put. If this is a zero-length string then the default backup set will be used. ═══ 4.2. BACKUPSETINFO ═══ typedef struct { char name[PSNS_NAME_SIZE + 1]; char description[PSNS_DESCRIPTION_SIZE + 1]; char storageDevice[PSNS_DEVICE_NAME + 1]; char incStorageDevice[PSNS_DEVICE_NAME + 1]; BOOL transferredIn; } BACKUPSETINFO, *PBACKUPSETINFO; name (char[]) Name of the backup set. description (char[]) Description of the backup set. storageDevice (char[]) Storage device which the backup set uses. For dual device backup sets this is the base device. incStorageDevice (char[]) For single device backup sets this is an empty string. For dual device backup sets this is the device incremental backups are written to. Note that once a backup set has been created it cannot be changed from a single device backup set to a dual device backup set or vice-versa. transferredIn (BOOL) TRUE if the backup set is transferred in and available for use; FALSE otherwise. ═══ 4.3. BACKUPSETVOLUME ═══ typedef struct { ULONG id; char backupSet[PSNS_NAME_SIZE + 1]; ULONG spaceUsed; } BACKUPSETVOLUME, *PBACKUPSETVOLUME; id (ULONG) Volume ID. backupSet (char[]) Name of the backup set. spaceUsed (ULONG) Space taken up on the volume by this backup set in units of unitMultiplier. ═══ 4.4. ESTIMATE ═══ typedef struct { PSNSFFB total; ULONG time; } ESTIMATE, *PESTIMATE; total (PSNSFFB) Files, folders and bytes counted. time (ULONG) Estimated time for the backup, in seconds. ═══ 4.5. EVENTINFO ═══ typedef enum { EV_REGULAR =1, // Regular interval event EV_DAILY =2, // Daily event EV_STARTUP =3, // Startup event EV_NAMEDDAYS=4, // Named days event EV_MONTHLY =5 // Monthly event } EVENTTYPE; typedef enum { EVENT_NO =-1, // No EVENT_AS_METHOD=0, // Use setting in backup method EVENT_YES =+1 // Yes } EVENTOPTION; typedef struct { USHORT id; EVENTTYPE type; char backupMethod[PSNS_NAME_SIZE + 1]; union { struct { int hours, minutes; } regular; struct { int hours, minutes; } daily; struct { int day, hours, minutes; } monthly; struct { int hours, minutes; char days, weeks; } namedDays; struct { int hours, minutes; } startup; } info; EVENTOPTION changedFilesOnly; EVENTOPTION showPreview; BOOL active; DATETIME lastRun; DATETIME nextRun; } EVENTINFO, *PEVENTINFO; id (USHORT) ID of the event. type (EVENTTYPE) Type of the event. backupMethod (char[]) Name of the backup method which will be run. info.regular Interval at which the regular event will occur, in hours and minutes. info.daily Time of day when the daily event will occur, in hours and minutes. info.monthly Day of the month and time of day when the monthly event will occur. info.namedDays hours, minutes Time of day when the event will occur. days Bit-field specifying on which days the event will occur: 1 = Monday, 2 = Tuesday, 4 = Wednesday and so on. weeks Bit-field specifying in which weeks of the month the event will occur: 1 = First week, 2 = second, 4 = third, 8 = fourth, 16 = last. info.startup Hours and minutes after startup when the event will occur. changedFilesOnly (EVENTOPTION) EVENT_YES Only back up files which have changed since the last backup. EVENT_NO Back up all files, whether or not they have changed. EVENT_AS_METHODUse the backup method to decide whether to back up changed files. showPreview (EVENTOPTION) EVENT_YES Show a preview before performing the backup. EVENT_NO Do not show a preview. EVENT_AS_METHODUse the backup method to decide whether to show a preview. active (BOOL) TRUE The event is active. FALSE The event is inactive and will not occur. lastRun (DATETIME) Date and time when the event was last run. nextRun (DATETIME) Date and time when the event is next due to be run. ═══ 4.6. FILEFILTERINFO ═══ typedef enum { FILTER_TREE=1, FILTER_LIST=2 } FILEFILTERTYPE; typedef struct { FILEFILTERTYPE type; char name[PSNS_NAME_SIZE + 1]; char description[PSNS_DESCRIPTION_SIZE + 1]; int numRules; char searchFile[CCHMAXPATH]; } FILEFILTERINFO, *PFILEFILTERINFO; type (FILEFILTERTYPE) Type of the file filter. FILTER_TREE Tree-based filter. FILTER_LIST Rule-based filter. In fact all file filters are stored as rule-based filters; the type only affects how the file filter is displayed when it is edited. name (char[]) Name of the file filter. description (char[]) Description of the file filter. numRules (int) Number of rules in the file filter. searchFile (char[]) This field is only used when listing file filters; it specifies a filename to match. All file filters which select this file will be listed. ═══ 4.7. FILEFILTERRULE ═══ typedef struct { char drive; char directory[CCHMAXPATH]; char pattern[CCHMAXPATH]; BOOL subdirectories; BOOL include; } FILEFILTERRULE, *PFILEFILTERRULE; drive (char) Drive letter to include/exclude, or an asterisk (*) for all drives. directory (char[]) Directory to include/exclude. pattern (char[]) Wildcard specifying which files to include/exclude. subdirectories (BOOL) TRUE Also include/exclude subdirectories in the specified directory. FALSE Do not include/exclude subdirectories. include (BOOL) TRUE Include the specified files. FALSE Exclude the specified files. ═══ 4.8. HPSNSLIST ═══ typedef int HPSNSLIST, *PHPSNSLIST; ═══ 4.9. PSNSCOMPRESSION ═══ typedef enum { PSNS_NOCOMPRESSION, PSNS_COMPRESSION, PSNS_DEFAULT } PSNSCOMPRESSION; ═══ 4.10. PSNSCONNECTION ═══ typedef enum { PSNS_PIPE, PSNS_TCPIP } PSNSCONNECTION; typedef struct { char serverName[CCHMAXPATH]; char pipeName[CCHMAXPATH]; } PSNSPIPEINFO, *PPSNSPIPEINFO; serverName (char[]) Name of the server to connect to, or empty for a local server. pipeName (char[]) Name of the pipe to connect to on that server, or empty for the default. ═══ 4.11. PSNSDEFAULTS ═══ typedef struct { char fileFilter[PSNS_SIZE_NAME + 1]; char rulebook[PSNS_SIZE_NAME + 1]; char backupSet[PSNS_SIZE_NAME + 1]; BOOL compression; int generations; } PSNSDEFAULTS, *PPSNSDEFAULTS; fileFilter (char[]) Name of the default file filter. rulebook (char[]) Name of the default rulebook. backupSet (char[]) Name of the default backup set. compression (BOOL) TRUE Do compress data by default. FALSE Don't compress data by default. generations (int) Default number of generations to keep. ═══ 4.12. PSNSFFB ═══ typedef struct { unsigned long files, folders; ULONG64 bytes; } PSNSFFB, *PPSNSFFB; ═══ 4.13. PSNSFILEINFO ═══ typedef struct { char backupSet[PSNS_NAME_SIZE + 1]; char filename[CCHMAXPATH]; short generations; short thisGeneration; FDATE creationDate; FTIME creationTime; FDATE writeDate; FTIME writeTime; FDATE backupDate; FTIME backupTime; ULONG size; ULONG attribs; ULONG volumeID; } PSNSFILEINFO, *PPSNSFILEINFO; backupSet (char[]) Name of the backup set to which this file is backed up. filename (char[]) Original name and path of the file. generations (short) Number of generations of this file which are backed up to this backup set. thisGeneration (short) Number of the generation to which the information in this structure refers. creationDate (FDATE) Date when the backed-up file was created. creationTime (FTIME) Time when the backed-up file was created. writeDate (FDATE) Date when the backed-up file was last changed. writeTime (FTIME) Time when the backed-up file was last changed. backupDate (FDATE) Date when this generation was backed up. backupTime (FTIME) Time when this generation was backed up. size (ULONG) Size of the file. attribs (ULONG) File attributes, in the form returned by DosQueryFileInfo. volumeID (ULONG) ID of the volume on which this generation is stored. ═══ 4.14. PSNSHANDLE ═══ typedef unsigned long PSNSHANDLE; ═══ 4.15. PSNSMESSAGEFN ═══ typedef ULONG (*PSNSMESSAGEFN)(const char *msg, ULONG style, void *privates); This type defines a callback function which can be registered using PsnsMessageCallback and will be called every time there is a message or query which might be shown to the user. There are three arguments: msg (const char *) Message text style (ULONG) Flags describing which options are available to the user. PSNSM_OK OK PSNSM_RETRY Retry PSNSM_IGNORE Ignore PSNSM_CANCEL Cancel PSNSM_YES Yes PSNSM_NO No PSNSM_ABORT Abort privates (void *) The pointer which was passed to PsnsMessageCallback. The function should return one of these constants to indicate which choice the user made. A return value of PSNSM_DEFAULT is also allowed, which causes some default action to be taken; this would for example be used when user interaction is not possible. Example ═══ 4.16. PSNSSETTINGS ═══ typedef enum { NORMAL=1, HIGH =2 } PSNSPRIORITY; typedef struct { PSNSPRIORITY manualPriority; PSNSPRIORITY autoPriority; char tempPath[CCHMAXPATH]; long flags; ULONG logFileLimit; char backupExit[CCHMAXPATH]; char restoreExit[CCHMAXPATH]; BOOL enableACLBackup; char uadFilename[CCHMAXPATH]; } PSNSSETTINGS, *PPSNSSETTINGS; manualPriority (PSNSPRIORITY) Priority for manual backups. autoPriority (PSNSPRIORITY) Priority for automatic backups. tempPath (char[]) Path for temporary files. flags (long) Various on/off flags: SET_LOG Enable logging for backup, restore and drop activities. SET_LOG_SUCCESSESLog individual files which are successful. SET_LOG_FAILURESLog individual files which fail. SET_BACKUP_EXITEnable the user exit on backup. SET_RESTORE_EXITEnable the user exit on restore. logFileLimit (ULONG) Maximum number of lines in a log file. If this is 0 then there is no limit to the size of a log file. backupExit (char[]) Name of a Rexx command file to run on backup. restoreExit (char []) Name of a Rexx command file to run on restore. enableACLBackup (BOOL) TRUE Back up and restore Access Control Lists using BACKACC and RESTACC. FALSE Do not back up and restore Access Control Lists. uadFilename (char[]) Name of the file which contains the User Accounts Database, usually NET.ACC. For more information on Rexx user exits and on backing up Access Control Lists, see the OS/2 Warp Server Backup/Restore online help. ═══ 4.17. PSNSSTATSFN ═══ typedef struct { PSNSFFB total, processed, failed; unsigned long timeElapsed, timeEstimate; // in seconds unsigned long dataRate; // bytes per second ULONG64 spaceLeft; } PSNSSTATS, *PPSNSSTATS; typedef void (*PSNSSTATSFN)(PPSNSSTATS pPsnsStats, char *message); This type defines a callback function which is called during PsnsRunBackupMethod and PsnsRunRestoreMethod. The function is called whenever there are statistics or messages which might interest the user. If the pPsnsStats parameter is non-NULL, it points to a PSNSSTATS structure which contains statistics about the backup or restore operation. If the message parameter is non-NULL, it contains a filename or a message. ═══ 4.18. RESTOREMETHODINFO ═══ typedef struct { char name[PSNS_SIZE_NAME + 1]; char description[PSNS_SIZE_DESCRIPTION + 1]; char backupSet[PSNS_SIZE_NAME + 1]; BOOL allFiles; char drive; char directory[CCHMAXPATH]; char pattern[CCHMAXPATH]; BOOL subdirectories; BOOL byDate; FDATE date; FTIME time; BOOL preview; BOOL prompt; BOOL originalLocation; char destinationDrive; char destinationPath[CCHMAXPATH]; } RESTOREMETHODINFO, *PRESTOREMETHODINFO; name (char[]) Name of the restore method. description (char[]) Description of the restore method. backupSet (char[]) Backup set from which to restore. This can be an asterisk (*) to restore from all backup sets, or an empty string to restore from the default backup set. allFiles (BOOL) TRUE Restore all files in the backup set; the drive, directory, pattern and subdirectories fields are ignored. FALSE Restore only the files specified in the drive, directory, pattern and subdirectories fields. drive (char) Original drive of the files to be restored. directory (char[]) Original directory of the files to be restored. pattern (char[]) Wildcard selecting which files are to be restored. subdirectories (BOOL) TRUE Restore files in subdirectories of the selected directories. FALSE Do not restore files in subdirectories. byDate (BOOL) TRUE Restore files as they were on the date and time specified in date and time. FALSE Restore the most recent generation of each file. date (FDATE) Files will be restored to the state they were in on this date if byDate is set to TRUE. time (FTIME) Files will be restored to the state they were in at this time if byDate is set to TRUE. preview (BOOL) TRUE Show a preview and allow the user to select or deselect individual files before performing the restore. FALSE Do not show a preview. Note: Showing a preview is only useful if the restore method is to be run from the OS/2 Warp Server Backup/Restore window; it is not possible to show a preview when running a restore method using the API. prompt TRUE Prompt the user to select a generation of each file to be restored. FALSE Do not prompt the user; restore the most recent generation of each file. Note: This is only useful if the restore method is to be run from the OS/2 Warp Server Backup/Restore window; it is not possible to pick generations when running a restore method using the API. originalLocation (BOOL) TRUE Restore files to their original locations; destinationDrive and destinationPath are ignored. FALSE Restore files to the drive and path specified in destinationDrive and destinationPath. destinationDrive (char) Drive to which to restore files if originalLocation is set to FALSE destinationPath (char[]) Path to which to restore files if originalLocation is set to FALSE ═══ 4.19. RULEBOOKINFO ═══ typedef struct { char name[PSNS_NAME_SIZE + 1]; char description[PSNS_DESCRIPTION_SIZE + 1]; int numRules; } RULEBOOKINFO, *PRULEBOOKINFO; name (char[]) Name of the rulebook. description (char[]) Description of the rulebook. numRules (int) Number of rules in the rulebook. ═══ 4.20. RULEBOOKRULE ═══ typedef struct { char drive; char directory[CCHMAXPATH]; char pattern[CCHMAXPATH]; BOOL subdirectories; int generations; PSNSCOMPRESSION compression; } RULEBOOKRULE, *PRULEBOOKRULE; drive (char) Drive letter to include/exclude, or anasterisk (*) for all drives. directory (char[]) Directory to include/exclude. pattern (char[]) Wildcard specifying which files to include/exclude. subdirectories (BOOL) TRUE Also select subdirectories in the specified directory. FALSE Do not select subdirectories. generations (int) Number of generations of the specified files to keep. compression (PSNSCOMPRESSION) PSNS_COMPRESSIONCompress the specified files. PSNS_NOCOMPRESSIONDo not compress the specified files. PSNS_DEFAULT Use the default compression for the specified files. ═══ 4.21. SOURCEDRIVEINFO ═══ typedef enum { DRI_HARDDISK =1, DRI_DISKETTE =2, DRI_LANDRIVE =3, DRI_RWOPTICAL=4, DRI_CDROM =5, DRI_PRM =6 DRI_OTHER =7 } DRIVETYPE; typedef struct { char letter; DRIVETYPE type; BOOL selected; } SOURCEDRIVEINFO, *PSOURCEDRIVEINFO; letter (char) Drive letter of the source drive. type (DRIVETYPE) Type of the source drive. selected (BOOL) TRUE This drive will be checked for files to back up. FALSE This drive will not be checked for files to back up. ═══ 4.22. STORAGEDEVICEINFO ═══ typedef struct { char name[PSNS_DEVICE_NAME + 1]; char dllName[CCHMAXPATH]; } STORAGEDEVICEINFO, *PSTORAGEDEVICEINFO; name (char[]) Name of the storage device. dllName (char[]) Name of the Dynamic Link Library (DLL) which implements the storage device. ═══ 4.23. ULONG64 ═══ typedef struct { unsigned long high, low; } ULONG64, *PULONG64; This structure is used for storing quantities which do not fit into a 32-bit integer. high (unsigned long) High 32 bits. low (unsigned long) Low 32 bits. ═══ 4.24. VOLUMEINFO ═══ typedef struct { ULONG id; char name[PSNS_VOLUME_NAME_SIZE + 1]; char storageDevice[PSNS_DEVICE_NAME + 1]; BOOL transferredOut; BOOL available; char backupSets; ULONG unitMultiplier; ULONG totalCapacity; ULONG psnsCapacity; ULONG psnsUsed; ULONG psnsFree; ULONG otherFree; ULONG otherUsed; ULONG totalBad; char backupSet[PSNS_NAME_SIZE+1]; LONG indexNo; } VOLUMEINFO, *PVOLUMEINFO; id (ULONG) Volume ID of the volume. name (char[]) Name of the volume. storageDevice (char[]) Name of the storage device which the volume uses. Index diskettes have an empty string here. transferredOut (BOOL) TRUE The volume belongs to a backup set which has been transferred out. FALSE The volume does not belong to a backup set which has been transferred out. available (BOOL) TRUE The volume is available for use. FALSE The user has made the volume unavailable and it will not be used for backing up or restoring data. backupSets (char) Number of backup sets which use this volume. unitMultiplier (ULONG) This specifies the units in which the volume usage information is specified. It is a number in bytes, for example 1024 for kilobytes. totalCapacity (ULONG) Total size of the volume in units of unitMultiplier. psnsCapacity (ULONG) Amount of space on the volume, in units of unitMultiplier, which is available for OS/2 Warp Server Backup/Restore to use. psnsUsed (ULONG) Amount of space, in units of unitMultiplier, currently used on the volume by OS/2 Warp Server Backup/Restore. psnsFree (ULONG) Amount of free space on the volume, in units of unitMultiplier, which OS/2 Warp Server Backup/Restore may use. otherFree (ULONG) Amount of free space on the volume, in units of unitMultiplier, which OS/2 Warp Server Backup/Restore may not use. otherUsed (ULONG) Amount of space on the volume, in units of unitMultiplier, used by programs other than OS/2 Warp Server Backup/Restore. totalBad (ULONG) Total amount of unusable space on the volume, in units of unitMultiplier. char backupSet (char[]) If the volume is used for only one backup set, this contains the name of that backup set. indexNo (LONG) If the volume is used for only one backup set, this contains the index of the volume within the backup set. A negative value signifies that the volume is an index diskette. A value of zero means that the volume is unassociated or fixed. ═══ 5. Errors ═══ 0 PSNS_OK No errors occurred. 1 PSNS_NO_MORE_HANDLES Too many list handles are in use and a new one cannot be allocated. 3 PSNS_UNKNOWN_ERROR An unknown internal error occurred. 4 PSNS_HANDLE_IN_USE An API call is already in progress using this handle. You may not call more than one API function at the same time with the same handle. If another thread needs to call API functions, it should obtain a new handle using PsnsInit. 5 PSNS_ALREADY_EXISTS You are trying to create, copy or rename an object, but the name you have specified already exists. 6 PSNS_ARCHIVE_ERROR An internal error was encountered when processing index files. 7 PSNS_INVALID_HANDLE The handle you have passed is not one which was returned by PsnsInit. 8 PSNS_INVALID_LIST_HANDLE The list handle you have passed to a listing function is not known. 9 PSNS_INVALID_PARAMETER A parameter passed to an API function is invalid, for example, a pointer is NULL when it shouldn't be. 10 PSNS_INVALID_BACKUP_METHOD The named backup method does not exist. 11 PSNS_INVALID_VOLUME The given volume ID does not exist. 12 PSNS_INVALID_EVENT_TYPE The given event type is not one defined in EVENTTYPE. 13 PSNS_INVALID_EVENT_OPTION The given event option is not one defined in EVENTOPTION. 14 PSNS_INVALID_MASK The mask you have supplied does not make sense, for example, searching for files which are both larger and smaller than 10kB. 15 PSNS_INVALID_DRIVE_TYPE The given drive type is not one defined in DRIVETYPE. 16 PSNS_INVALID_GENERATIONS The number of generations you have specified is not allowed; the number of generations must be between 1 and 250. 17 PSNS_INVALID_RULEBOOK The named rulebook does not exist. 18 PSNS_INVALID_FILE_FILTER The named file filter does not exist. 19 PSNS_INVALID_BACKUP_SET The named backup set does not exist. 20 PSNS_INVALID_RESTORE_METHOD The named restore method does not exist. 21 PSNS_INVALID_SOURCE_DRIVE You gave an invalid character for a source drive letter. 22 PSNS_INVALID_POSITION The position you referred to in a rule or file filter is out of range. 23 PSNS_INVALID_EVENT The given event ID does not exist. 24 PSNS_INVALID_DRIVE The specified drive is not a valid drive letter. 25 PSNS_INVALID_PATH The specified path is not valid. 26 PSNS_INVALID_FILENAME The specified filename is not valid. 27 PSNS_ALREADY_ASSOCIATED The volume is already associated with a backup set. 28 PSNS_INVALID_NAME The name you gave when creating, copying or renaming an object is not valid. See object names for a description of what constitutes a valid object name. 29 PSNS_INVALID_FILE_FILTER_TYPE The given file filter type is not one defined in FILEFILTERTYPE. 30 PSNS_INVALID_STORAGE_DEVICE_TYPE The given storage device type does not exist as a creatable storage device type. 31 PSNS_INVALID_STORAGE_DEVICE The named storage device does not exist. 32 PSNS_IN_USE You tried to delete or change an object which is currently in use and therefore cannot be deleted or changed. 33 PSNS_CANNOT_DELETE You tried to delete a storage device or volume which may not be deleted. 34 PSNS_FILE_NOT_FOUND The named file was not found in the backup set. 35 PSNS_INVALID_TIME The time you specified for an event is not valid. 36 PSNS_NO_EVENTS There are no events currently scheduled. 37 PSNS_TOO_MUCH_DATA The buffer you supplied is not large enough to receive all the data which would be returned; the data has been truncated to fit in the buffer. 38 PSNS_CANT_CONNECT An error occurred when trying to connect to the API server. 39 PSNS_INVALID_CONFIGURATION The configuration string you gave for a storage device or backup method is not valid. 40 PSNS_INVALID_PRIORITY The given priority is not one defined in PSNSPRIORITY. 41 PSNS_INVALID_GENERATION The generation you specified does not exist. 42 PSNS_TRANSFERRED_IN The backup set was already transferred in. 43 PSNS_TRANSFERRED_OUT The backup set was already transferred out, or you tried to perform an operation using a backup set which is transferred out. 44 PSNS_INVALID_COMPRESSION The specified compression option is not valid. 45 PSNS_MALFORMED_METHOD Some options in the backup or restore method are not compatible with each other. 46 PSNS_INVALID_DATE The given date is not valid. 47 PSNS_READONLY You tried to change a rule which cannot be changed. 48 PSNS_NOT_CONFIGURABLE The backup set or storage device configuration cannot be changed now. 49 PSNS_INVALID_FLAGS The flags you specified in PsnsSettings are not valid. 50 PSNS_COMMUNICATIONS_ERROR Contact with the API server has been lost; all handles to that server have been closed. 51 PSNS_INVALID_RC The return code passed to PsnsGetMessageText is not valid. 52 PSNS_INDEX_DISKETTE The volume ID passed to PsnsActivateVolume is that of an index diskette. The active state of index diskettes cannot be altered in this way. 53 PSNS_FIXED_VOLUME An API function for working with removable volumes has been passed the ID of a fixed volume. 54 PSNS_INAPPROPRIATE_BACKUP_SET The backup set passed to PsnsAssociateVolume is not appropriate for association with the volume. 55 PSNS_INVALID_KEYWORD A keyword in a configuration string is incorrect, for example, using the BEEP keyword with an ADSM storage device. 56 PSNS_INVALID_VALUE A value in a configuration string is incorrect, for example, a non-numeric was found where a numeric value was expected. 57 PSNS_SYNTAX_ERROR A configuration string did not conform to the format described in Storage Device & Backup Set Configuration. 58 PSNS_INCOMPLETE_STRING A required parameter was missing from the configuration string. 59 PSNS_SEMANTIC_ERROR An error occurred whilst processing a configuration string, for example, a path name is invalid. 60 PSNS_ERROR_DURING_BACKUP There were errors during the backup. If the logging of failures is enabled, the backup set log contains details of the errors. 61 PSNS_ERROR_DURING_RESTORE There were errors during the restore. If the logging of failures is enabled, the backup set log contains details of the errors. 62 PSNS_UNHANDLED_EXCEPTION An OS/2 Warp Server Backup/Restore internal error occurred; there was an unhandled exception. ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListBackupMethods */ /* PsnsDeleteBackupMethod */ /* */ /* Find all backup methods which use backup set */ /* 'Llama', and delete them. */ /****************************************************/ HPSNSLIST hlist = 0; BACKUPMETHODINFO info; int rc; /* Set up the search criteria with the backup set */ /* we want to search on. */ strcpy(info.backupSet, "Llama"); /* Now list all the backup methods which use this */ /* backup set. */ do { rc = PsnsListBackupMethods(handle, &hlist, &info, BM_BACKUPSET); if(!rc && hlist) { /* For every backup method returned, print its name */ /* and delete it. */ printf("Found backup method '%s'\n", info.name); rc = PsnsDeleteBackupMethod(handle, info.name); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) printf("Error encountered, rc = %d\n", rc); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateBackupMethod */ /* PsnsBackupMethodInfo */ /* PsnsEstimateBackupMethod */ /* */ /* Create a backup method to back up all changed */ /* files on drive E, and find out how many files */ /* would be backed up. */ /****************************************************/ BACKUPMETHODINFO info = { 0 }; ESTIMATE estimate; int rc; /* First create a new backup method. */ rc = PsnsCreateBackupMethod(handle, "Drive E to Llama"); if(rc) { printf("PsnsCreateBackupMethod returned %d\n", rc); return 1; } /* Now set up the backup method to do what we want. */ strcpy(info.description, "Backs up drive E to backup set Llama"); info.allFiles = FALSE; info.drive = 'E'; strcpy(info.directory, "*"); info.subdirectories = TRUE; info.compression = TRUE; info.generations = 2; info.useRulebook = FALSE; info.useFileFilter = FALSE; info.changedFilesOnly = TRUE; info.preview = FALSE; strcpy(info.backupSet, "Llama"); rc = PsnsBackupMethodInfo(handle, "Drive E to Llama", &info, BM_ALL); if(rc) { printf("PsnsBackupMethodInfo returned %d\n", rc); return 1; } /* Estimate the backup method. */ rc = PsnsEstimateBackupMethod(handle, "Drive E to Llama", &estimate); if(rc) { printf("PsnsEstimateBackupMethod returned %d\n", rc); return 1; } else { printf("Files Folders\n"); printf("%8d %8d\n", estimate.total.files, estimate.total.folders); printf("Estimated time: %d seconds\n", estimate.time); } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRenameBackupMethod */ /* */ /* Rename backup method 'Orange' to 'Apple'. */ /****************************************************/ int rc; rc = PsnsRenameBackupMethod(handle, "Orange", "Apple"); if(rc) { printf("PsnsRenameBackupMethod returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCopyBackupMethod */ /* */ /* Copy backup method 'Orange' to 'Orange Mk II'. */ /****************************************************/ int rc; rc = PsnsCopyBackupMethod(handle, "Orange", "Orange Mk II"); if(rc) { printf("PsnsCopyBackupMethod returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRunBackupMethod */ /* */ /* Run backup method 'Orange' and display progress */ /* information. */ /****************************************************/ /* First define the statistics callback function. */ void show_stats(PPSNSSTATS stats, char *message) { if(message) printf("** %s\n", message); if(stats) printf("%8d %8d\n", stats->processed.files, stats->processed.folders); } . . . int rc; /* Run the backup method */ printf("Files Folders\n-------- --------\n"); rc = PsnsRunBackupMethod(handle, "Orange", show_stats); if(rc) { printf("PsnsRunBackupMethod returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsInit */ /* PsnsTerm */ /* */ /* Establish a connection to PSnS and then close it */ /* again. */ /****************************************************/ int rc; PSNSPIPEINFO pipeinfo; PSNSHANDLE handle; /* Set up the structure saying where we want to */ /* connect to. */ strcpy(pipeinfo.serverName, "WDGSRV"); pipeinfo.pipeName[0] = '\0'; /* Connect to PSnS */ rc = PsnsInit(&handle, PSNS_PIPE, &pipeinfo); if(rc) { printf("PsnsInit returned %d\n", rc); return 1; } printf("Connection established\n"); /* Disconnect */ PsnsTerm(handle); printf("Connection terminated\n"); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListRestoreMethods */ /* PsnsDeleteRestoreMethod */ /* */ /* Find all restore methods which use backup set */ /* 'Llama', and delete them. */ /****************************************************/ HPSNSLIST hlist = 0; RESTOREMETHODINFO info; int rc; /* Set up the search criteria with the backup set */ /* we want to search on. */ strcpy(info.backupSet, "Llama"); /* Now list all the restore methods which use this */ /* backup set. */ do { rc = PsnsListRestoreMethods(handle, &hlist, &info, RM_BACKUPSET); if(!rc && hlist) { /* For every restore method returned, print its name */ /* and delete it. */ printf("Found restore method '%s'\n", info.name); rc = PsnsDeleteRestoreMethod(handle, info.name); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) printf("Error encountered, rc = %d\n", rc); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateRestoreMethod */ /* PsnsRestoreMethodInfo */ /* PsnsEstimateRestoreMethod */ /* */ /* Create a restore method to restore all .c files */ /* to their original locations, and find out how */ /* many files would be restored. */ /****************************************************/ RESTOREMETHODINFO info; ESTIMATE estimate; int rc; /* First create a new restore method. */ rc = PsnsCreateRestoreMethod(handle, "C files"); if(rc) { printf("PsnsCreateRestoreMethod returned %d\n", rc); return 1; } /* Now set up the restore method to do what we want. */ strcpy(info.description, "Restores all .c files"); strcpy(info.backupSet, "*"); info.allFiles = FALSE; info.drive = '*'; strcpy(info.directory, "*"); strcpy(info.pattern, "*.c"); info.subdirectories = TRUE; info.byDate = FALSE; info.preview = FALSE; info.prompt = FALSE; info.originalLocation = TRUE; rc = PsnsRestoreMethodInfo(handle, "C files", &info, RM_ALL); if(rc) { printf("PsnsRestoreMethodInfo returned %d\n", rc); return 1; } /* Estimate the restore method. */ rc = PsnsEstimateRestoreMethod(handle, "C files", &estimate); if(rc) { printf("PsnsEstimateRestoreMethod returned %d\n", rc); return 1; } else { printf("Files Folders\n"); printf("%8d %8d\n", estimate.total.files, estimate.total.folders); printf("Estimated time: %d seconds\n", estimate.time); } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRenameRestoreMethod */ /* */ /* Rename restore method 'Gibbon' to 'All C files'. */ /****************************************************/ int rc; rc = PsnsRenameRestoreMethod(handle, "Gibbon", "All C files"); if(rc) { printf("PsnsRenameRestoreMethod returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCopyRestoreMethod */ /* */ /* Copy restore method 'Fish' to 'Haggis'. */ /****************************************************/ int rc; rc = PsnsCopyRestoreMethod(handle, "Fish", "Haggis"); if(rc) { printf("PsnsCopyRestoreMethod returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRunRestoreMethod */ /* */ /* Run restore method 'C files' and display */ /* progress information. */ /****************************************************/ /* First define the statistics callback function. */ void show_stats(PPSNSSTATS stats, char *message) { if(message) printf("** %s\n", message); if(stats) printf("%8d %8d\n", stats->processed.files, stats->processed.folders); } . . . int rc; /* Run the restore method */ printf("Files Folders\n-------- --------\n"); rc = PsnsRunRestoreMethod(handle, "C files", show_stats, 0, 0); if(rc) { printf("PsnsRunRestoreMethod returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListBackupSets */ /* PsnsTransferBackupSet */ /* */ /* Find all backup sets which use storage device */ /* 'Drive E', and transfer them out. */ /****************************************************/ HPSNSLIST hlist = 0; BACKUPSETINFO info; int rc; /* Set up the search criteria with the storage */ /* device we want to search on. */ strcpy(info.storageDevice, "Drive E"); /* Now list all the backup sets which use this */ /* storage device. */ do { rc = PsnsListBackupSets(handle, &hlist, &info, BS_STORAGEDEVICE); if(!rc && hlist) { /* For every backup set returned, print its name */ /* and transfer it out. */ printf("Found backup method '%s'\n", info.name); rc = PsnsTransferBackupSet(handle, info.name, FALSE, 0); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) printf("Error encountered, rc = %d\n", rc); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateBackupSet */ /* PsnsBackupSetInfo */ /* */ /* Create a single device backup set on storage */ /* device 'Drive E' and set its description. */ /****************************************************/ BACKUPSETINFO info = { 0 }; int rc; /* Create the backup set */ rc = PsnsCreateBackupSet(handle, "Llama", "Drive E", "PATH=LlamaBackup", NULL, NULL); if(rc) { printf("PsnsCreateBackupSet returned %d\n", rc); return 1; } /* Set the description */ strcpy(info.description, "Contains complete backup of the Llama Files"); rc = PsnsBackupSetInfo(handle, "Llama", &info, BS_DESCRIPTION); if(rc) { printf("PsnsBackupSetInfo returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsDeleteBackupSet */ /* */ /* Delete backup set "Llama". */ /****************************************************/ char answer[4]; int rc; printf("Are you sure you want to do this? Type 'yes' to proceed.\n"); fgets(answer, 4, stdin); if(strcmp(answer, "yes") == 0) rc = PsnsDeleteBackupSet(handle, "Llama"); if(rc) { printf("PsnsDeleteBackupSet returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsEmptyBackupSet */ /* */ /* Empty backup set "Llama". */ /****************************************************/ char answer[4]; int rc; printf("Are you sure you want to lose this valuable data? Type 'yes' to proceed.\n"); fgets(answer, 4, stdin); if(strcmp(answer, "yes") == 0) rc = PsnsEmptyBackupSet(handle, "Llama"); if(rc) { printf("PsnsEmptyBackupSet returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsGetLogFile */ /* */ /* Delete the log file for backup set 'Llama'. */ /****************************************************/ char logfile[CCHMAXPATH]; int rc; rc = PsnsGetLogFile(handle, "Llama", logfile); if(rc) { printf("PsnsGetLogFile returned %d\n", rc); return 1; } DosDelete(logfile); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListStorageDevices */ /* PsnsCreateStorageDevice */ /* */ /* List the creatable storage devices, prompt the */ /* user to select one, and create a new storage */ /* device. */ /****************************************************/ int rc, i = 0, j; HPSNSLIST hlist = 0; STORAGEDEVICEINFO info; char answer[4]; char *names[20]; char newname[PSNS_NAME_SIZE]; /* Display a list of the creatable storage devices */ printf("Select a storage device to create:\n"); do { rc = PsnsListStorageDevices(handle, &hlist, &info, SD_CREATABLE); if(!rc && hlist) { names[i] = strdup(info.name); printf(" %2d. %s\n", ++i, info.name); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) { printf("PsnsListStorageDevices returned %d\n", rc); return 1; } /* Wait for the user to make a selection */ fgets(answer, 4, stdin); j = atoi(answer); if(j <= 0 || j > i) printf("You entered an invalid selection\n"); else { /* get the configuration from the user */ char config[ 260]; printf( "Enter the configuration string for the device\n"); fgets( config, 260, stdin); /* Create a new storage device */ rc = PsnsCreateStorageDevice(handle, names[j-1], config, newname); if(rc) { printf("PsnsCreateStorageDevice returned %d\n", rc); return 1; } printf("New storage device is '%s'.\n", newname); } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRefreshStorageDevices */ /* */ /* Refresh the list of available storage devices. */ /****************************************************/ int rc; rc = PsnsRefreshStorageDevices(handle); if(rc) { printf("PsnsRefreshStorageDevices returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsDeleteStorageDevice */ /* */ /* Delete storage device 'Drive E'. */ /****************************************************/ int rc; rc = PsnsDeleteStorageDevice(handle, "Drive E"); if(rc) { printf("PsnsDeleteStorageDevice returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsStorageDeviceInfo */ /* */ /* Find out which dynamic link library (DLL) is */ /* used by storage device "Drive E". */ /****************************************************/ int rc; STORAGEDEVICEINFO info; rc = PsnsStorageDeviceInfo(handle, "Drive E", &info, SD_NONE); if(rc) { printf("PsnsStorageDeviceInfo returned %d\n", rc); return 1; } printf("DLL name: %s\n", info.dllName); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsVolumeInfo */ /* PsnsListVolumeBackupSets */ /* */ /* Print out space usage information for a volume. */ /****************************************************/ void PrintSpaceUsage(PSNSHANDLE handle, ULONG volID) { HPSNSLIST hlist = 0; VOLUMEINFO volInfo; BACKUPSETVOLUME bksVol; int rc; rc = PsnsVolumeInfo(handle, volID, &volInfo, 0); if(rc) return rc; printf("Free space: %d\nSpace used by PSnS: %d\n", volInfo.otherFree + volume.psnsFree, volInfo.psnsUsed); bksVol.id = volID; do { rc = PsnsListVolumeBackupSets(handle, &hlist, &bksVol); if(!rc && hlist) printf(" Backup set '%s': %d\n", bksVol.backupSet, bksVol.spaceUsed); } while(!rc && hlist); return rc; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListVolumes */ /* PsnsDeleteVolume */ /* */ /* Find all volumes on a storage device which have */ /* no space used on them, and delete them. */ /****************************************************/ int rc; VOLUMEINFO info; HPSNSLIST hlist = 0; /* Set up the search criteria */ strcpy(info.storageDevice, "Diskette A (3.5\")"); /* Search for this storage device */ info.psnsUsed = 1; /* and less than 1 byte used */ do { rc = PsnsListVolumes(handle, &hlist, &info, VOL_STORAGEDEVICE | VOL_PSNSUSED_LESS); if(!rc && hlist) { printf("Found empty volume %d\n", info.name); rc = PsnsDeleteVolume(handle, info.id); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) { printf("Error encountered, rc = %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateVolume */ /* PsnsAssociateVolume */ /* PsnsActivateVolume */ /* */ /* Create a new diskette volume, associate it with */ /* backup set 'Llama' and mark it as inactive. */ /****************************************************/ int rc; VOLUMEINFO info; ULONG id; /* Create a new volume */ rc = PsnsCreateVolume(handle, "Diskette A (3.5\")", &id); if(rc) { printf("PsnsCreateVolume returned %d\n", rc); return 1; } printf("New volume ID = %lu\n", id); /* Associate the volume with a backup set */ rc = PsnsAssociateVolume(handle, id, "Llama"); if(rc) { printf("PsnsAssociateVolume returned %d\n", rc); return 1; } /* Mark the volume as inactive */ rc = PsnsActivateVolume(handle, id, FALSE); if(rc) { printf("PsnsActivateVolume returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateEvent */ /* PsnsEventInfo */ /* */ /* Create a new event to perform an hourly backup */ /* with backup method "Orange". */ /****************************************************/ int rc; EVENTINFO info; USHORT id; /* Create the new event */ rc = PsnsCreateEvent(handle, EV_REGULAR, "Orange", &id); if(rc) { printf("PsnsCreateEvent returned %d\n", rc); return 1; } printf("New event ID = %hu\n", id); /* Set up the time of the event */ info.info.regular.hours = 1; info.info.regular.minutes = 0; info.changedFilesOnly = EVENT_AS_METHOD; info.showPreview = EVENT_NO; info.active = TRUE; strcpy(info.backupMethod, "Orange"); rc = PsnsEventInfo(handle, id, &info, EV_ALL); if(rc) { printf("PsnsEventInfo returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListEvents */ /* PsnsActivateEvent */ /* */ /* List all events which use backup method "Apple" */ /* and deactivate them. */ /****************************************************/ int rc; EVENTINFO info; HPSNSLIST hlist = 0; /* Set up the search criteria */ strcpy(info.backupMethod, "Apple"); /* List all events which match the criteria */ do { rc = PsnsListEvents(handle, &hlist, &info, EV_BACKUPMETHOD); if(!rc && hlist) { printf("Found event, id = %hu\n", info.id); rc = PsnsActivateEvent(handle, info.id, FALSE); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) { printf("Error encountered, rc = %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsGetNextEvent */ /* PsnsDeleteEvent */ /* */ /* Find out which event is due to occur next, and */ /* delete it. */ /****************************************************/ int rc; EVENTINFO info; /* Get the next event to occur */ rc = PsnsGetNextEvent(handle, &info); if(rc == PSNS_NO_EVENTS) { printf("No events currently scheduled.\n"); return 0; } if(rc) { printf("PsnsGetNextEvent returned %d\n", rc); return 1; } printf("Next event is id = %hu.\n", info.id); /* Delete the event */ rc = PsnsDeleteEvent(handle, info.id); if(rc) { printf("PsnsDeleteEvent returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCopyEvent */ /* */ /* Copy event with the given ID and return the ID */ /* of the new event. */ /****************************************************/ USHORT CopyEvent(PSNSHANDLE handle, USHORT id) { USHORT newid; int rc; /* Copy the event */ rc = PsnsCopyEvent(handle, id, &newid); if(rc) { printf("PsnsCopyEvent returned %d\n", rc); return (USHORT)-1; } printf("New id = %hu\n", newid); return newid; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateFileFilter */ /* PsnsFileFilterInfo */ /* PsnsAddFileFilterRule */ /* */ /* Create a file filter to back up all the source */ /* files in Project Watermelon. */ /****************************************************/ int rc; FILEFILTERINFO info; FILEFILTERRULE rule; /* Create a new file filter */ rc = PsnsCreateFileFilter(handle, "Watermelon source", FILTER_LIST); if(rc) { printf("PsnsCreateFileFilter returned %d\n", rc); return 1; } /* Set the description */ strcpy(info.description, "Filter to select source for Project Watermelon"); rc = PsnsFileFilterInfo(handle, "Watermelon source", &info, FF_DESCRIPTION); if(rc) { printf("PsnsFileFilterInfo returned %d\n", rc); return 1; } /* Set up the first rule and add it */ rule.drive = 'D'; strcpy(rule.directory, "\\watermelon\\*\\"); strcpy(rule.pattern, "*.c"); rule.subdirectories = TRUE; rule.include = TRUE; rc = PsnsAddFileFilterRule(handle, "Watermelon source", &rule, 1); if(rc) { printf("PsnsAddFileFilterRule returned %d\n", rc); return 1; } /* Add more rules */ strcpy(rule.pattern, "*.cpp"); rc = PsnsAddFileFilterRule(handle, "Watermelon source", &rule, 1); if(rc) { printf("PsnsAddFileFilterRule returned %d\n", rc); return 1; } strcpy(rule.pattern, "*.h"); rc = PsnsAddFileFilterRule(handle, "Watermelon source", &rule, 1); if(rc) { printf("PsnsAddFileFilterRule returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListFileFilters */ /* PsnsDeleteFileFilter */ /* */ /* List all file filters which match the file */ /* E:\AARDVARK.EXE and delete them. */ /****************************************************/ HPSNSLIST hlist; FILEFILTERINFO info; int rc; /* Set up the search criteria */ strcpy(info.searchFile, "E:\\AARDVARK.EXE"); /* Now list all the file filters which match this */ /* file. */ do { rc = PsnsListFileFilters(handle, &hlist, &info, FF_SEARCHFILE); if(!rc && hlist) { /* For every file filter returned, print its name */ /* and delete it. */ printf("Found file filter '%s'\n", info.name); rc = PsnsDeleteFileFilter(handle, info.name); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) printf("Error encountered, rc = %d\n", rc); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRenameFileFilter */ /* */ /* Rename file filter 'Watermelon source' to */ /* 'my filter'. */ /****************************************************/ int rc; rc = PsnsRenameFileFilter(handle, "Watermelon source", "my filter"); if(rc) { printf("PsnsRenameFileFilter returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCopyFileFilter */ /* */ /* Copy file filter 'Watermelon source' to */ /* 'Watermelon II'. */ /****************************************************/ int rc; rc = PsnsCopyFileFilter(handle, "Watermelon source", "Watermelon II"); if(rc) { printf("PsnsCopyFileFilter returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsFileFilterInfo */ /* PsnsFileFilterRuleInfo */ /* */ /* Print out details of a file filter. */ /****************************************************/ int show_filter(PSNSHANDLE handle, const char *name) { FILEFILTERINFO info; FILEFILTERRULE rule; int rc, i; rc = PsnsFileFilterInfo(handle, name, &info, FF_NONE); if(rc) return rc; printf("File filter '%s'\n%s", info.name, info.description); for(i = 1; i <= info.numRules; i++) { rc = PsnsFileFilterRuleInfo(handle, name, i, &rule, FF_NONE); if(rc) return rc; printf(" %s %c:%s%s\\%s\n", rule.include ? "Include" : "Exclude", rule.drive, rule.directory, rule.subdirectories ? "\\*" : "", rule.pattern); } return 0; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsDeleteFileFilterRule */ /* */ /* Delete all the rules in a file filter. */ /****************************************************/ int rc; do { rc = PsnsDeleteFileFilterRule(handle, "Watermelon source", 1); } while(rc == 0); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCreateRulebook */ /* PsnsRulebookInfo */ /* PsnsAddRulebookRule */ /* */ /* Create a rulebook to keep 10 generations of all */ /* .foo and .bar files. */ /****************************************************/ int rc; RULEBOOKINFO info; RULEBOOKRULE rule; /* Create a new rulebook */ rc = PsnsCreateRulebook(handle, "My rulebook"); if(rc) { printf("PsnsCreateRulebook returned %d\n", rc); return 1; } /* Set the description */ strcpy(info.description, "Rulebook to keep 10 generations of .foo and .bar files"); rc = PsnsRulebookInfo(handle, "My rulebook", &info, RB_DESCRIPTION); if(rc) { printf("PsnsRulebookInfo returned %d\n", rc); return 1; } /* Set up the first rule and add it */ rule.drive = 'D'; strcpy(rule.directory, "\\"); strcpy(rule.pattern, "*.foo"); rule.subdirectories = TRUE; rule.generations = 10; rule.compression = PSNS_DEFAULT; rc = PsnsAddRulebookRule(handle, "My rulebook", &rule, 1); if(rc) { printf("PsnsAddRulebookRule returned %d\n", rc); return 1; } /* Add the other rule */ strcpy(rule.pattern, "*.bar"); rc = PsnsAddRulebookRule(handle, "My rulebook", &rule, 1); if(rc) { printf("PsnsAddRulebookRule returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListRulebooks */ /* PsnsDeleteRulebook */ /* */ /* List all rulebooks and delete them. */ /****************************************************/ HPSNSLIST hlist; RULEBOOKINFO info; int rc; /* List all rulebooks */ do { rc = PsnsListRulebooks(handle, &hlist, &info, RB_NONE); if(!rc && hlist) { /* For every rulebook returned, print its name and */ /* delete it. */ printf("Found rulebook '%s'\n", info.name); rc = PsnsDeleteRulebook(handle, info.name); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) printf("Error encountered, rc = %d\n", rc); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRenameRulebook */ /* */ /* Rename file filter 'My rulebook' to 'Spoon'. */ /****************************************************/ int rc; rc = PsnsRenameRulebook(handle, "My rulebook", "Spoon"); if(rc) { printf("PsnsRenameRulebook returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsCopyRulebook */ /* */ /* Copy file filter 'My rulebook' to */ /* 'My other rulebook'. */ /****************************************************/ int rc; rc = PsnsCopyRulebook(handle, "My rulebook", "My other rulebook"); if(rc) { printf("PsnsCopyRulebook returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRulebookInfo */ /* PsnsRulebookRuleInfo */ /* */ /* Print out details of a rulebook. */ /****************************************************/ int show_rulebook(PSNSHANDLE handle, const char *name) { RULEBOOKINFO info; RULEBOOKRULE rule; int rc, i; rc = PsnsRulebookInfo(handle, name, &info, RB_NONE); if(rc) return rc; printf("Rulebook '%s'\n%s", info.name, info.description); for(i = 1; i <= info.numRules; i++) { rc = PsnsRulebookRuleInfo(handle, name, i, &rule, RB_NONE); if(rc) return rc; printf("%c:%s%s\\%s\n : %d generations, %scompression", rule.drive, rule.directory, rule.subdirectories ? "\\*" : "", rule.pattern, rule.generations, rule.compression == PSNS_DEFAULT ? "default " : (rule.compression == PSNS_COMPRESSION ? "" : "no ")); } return 0; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsDeleteRulebookRule */ /* */ /* Delete all the rules in a rulebook. */ /****************************************************/ int rc; do { rc = PsnsDeleteRulebookRule(handle, "My rulebook", 1); } while(rc == 0); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListSourceDrives */ /* PsnsSelectSourceDrive */ /* */ /* Deselect all LAN drives for backup. */ /****************************************************/ HPSNSLIST hlist; SOURCEDRIVEINFO info; int rc; /* Set up the search criteria */ info.type = DRI_LANDRIVE; /* List all source drives */ do { rc = PsnsListSourceDrives(handle, &hlist, &info, DR_TYPE); if(!rc && hlist) { /* For every source returned, print its letter and */ /* deselect it. */ printf("Found LAN drive '%c'\n", info.letter); rc = PsnsSelectSourceDrive(handle, info.letter, FALSE); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) printf("Error encountered, rc = %d\n", rc); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsRefreshSourceDrives */ /* PsnsSourceDriveType */ /* */ /* Refresh the list of source drives, then set the */ /* type of drive H to be a hard disk. */ /****************************************************/ int rc; rc = PsnsRefreshSourceDrives(handle); if(rc) { printf("PsnsRefreshSourceDrives returned %d\n", rc); return 1; } rc = PsnsSourceDriveType(handle, 'H', DRI_HARDDISK); if(rc) { printf("PsnsSourceDriveType returned %d\n", rc); return 1; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsListFiles */ /* PsnsAddFile */ /* PsnsDropFiles */ /* PsnsPurgeFiles */ /* PsnsCloseList */ /* */ /* Find all files which have a generation backed */ /* up before a given date, and drop them. */ /****************************************************/ /* First define the statistics callback function. */ void show_stats(PPSNSSTATS stats, char *message) { if(message) printf("** %s\n", message); if(stats) printf("%8d %8d\n", stats->processed.files, stats->processed.folders); } int DropBefore(PSNSHANDLE handle, char *backupset, FDATE date) { HPSNSLIST hlist; PSNSFILEINFO info; short gen; int rc; /* Set up the search criteria */ strcpy(info.backupSet, backupset) info.backupDate = date; /* List all files which have a generation backed up before that date */ do { rc = PsnsListFiles(handle, &hlist, &info, FILE_BACKUPDATE_BEFORE | FILE_ALLGENERATIONS); if(!rc && hlist) { printf("%s - generation %h\n ", info.filename, info.thisGeneration); PsnsAddFile(handle, info.filename, info.thisGeneration); } } while(!rc && hlist); /* If we didn't get to the end of the list, close it */ if(hlist) PsnsCloseList(handle, &hlist); if(rc) { printf("Error encountered, rc = %d\nNo generations dropped.", rc); PsnsPurgeFiles(handle); return rc; } rc = PsnsDropFiles(handle, backupset, show_stats); return rc; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsDefaults */ /* PsnsSettings */ /* */ /* Show what the current defaults and settings are. */ /****************************************************/ PSNSSETTINGS settings; PSNSDEFAULTS defaults; int rc; rc = PsnsSettings(handle, &settings, SET_NONE); if(rc) { printf("PsnsSettings returned %d\n", rc); return 1; } printf("Manual backup priority: %s\n", settings.manualPriority == HIGH ? "High" : "Normal"); printf("Automatic backup priority: %s\n", settings.autoPriority == HIGH ? "High" : "Normal"); printf("Temporary file path: %s\n", settings.tempPath); printf("Logging: %s\n", settings.flags & SET_LOG ? "On" : "Off"); if(settings.flags & SET_LOG & SET_LOG_SUCCESSES) printf(" Log individial successes\n"); if(settings.flags & SET_LOG & SET_LOG_FAILURES) printf(" Log individial failures\n"); printf("Backup user exit %s\n", settings.flags & SET_BACKUP_EXIT ? "enabled" : "disabled"); printf("Restore user exit %s\n", settings.flags & SET_RESTORE_EXIT ? "enabled" : "disabled"); printf("ACL backup %s\n", settings.enableACLBackup ? "enabled" : "disabled"); if(settings.enableACLBackup) printf("UAD file: %s\n", settings.uadFilename); rc = PsnsDefaults(handle, &defaults, SET_NONE); if(rc) { printf("PsnsDefaults returned %d\n", rc); return 1; } printf("Default file filter: %s\n", defaults.fileFilter); printf("Default rulebook: %s\n", defaults.rulebook); printf("Default backup set: %s\n", defaults.backupSet); printf("Default compression: %s\n", defaults.compression ? "PSnS compression" : "No compression"); printf("Default generations: %d\n", defaults.generations); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsMessageCallback */ /* */ /* Register a message callback which logs errors to */ /* a file and then takes the default action. */ /****************************************************/ ULONG callback(const char *msg, ULONG style, void *privates) { FILE *f = (FILE *)privates; fputs(msg, f); fputc('\n', f); return PSNSM_DEFAULT; } . . . /* Main program */ FILE *f; f = fopen("D:\\PSNS\\API.LOG", "w"); PsnsMessageCallback(handle, callback, f); ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsGetMessageText */ /* */ /* Print out the message corresponding to an API */ /* error code. */ /****************************************************/ int print_message(PSNSHANDLE handle, int code) { int rc; char *buffer; ULONG cbString; rc = PsnsGetMessageText(handle, code, NULL, &cbString); if( rc) return rc; buffer = malloc( cbString); rc = PsnsGetMessageText(handle, code, buffer, &cbString); if( !rc) printf("* %s\n", buffer); free( buffer); return rc; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsGetLastError */ /* */ /* Print out the details of the last error for a */ /* handle. */ /****************************************************/ int last_error( PSNSHANDLE handle) { int rc; char *buffer; ULONG cbString; rc = PsnsGetLastError( handle, NULL, &cbString); if( !rc) return rc; buffer = malloc( cbString); rc = PsnsGetLastError( handle, buffer, &cbString); if( !rc) printf("* %s\n", buffer); free( buffer); return rc; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsPurgeFiles */ /* PsnsAddFile */ /* PsnsBackupFiles */ /* */ /* Back up a selection of files */ /****************************************************/ int rc; BACKUPMETHODINFO backupMethodInfo; /* empty the file list for this handle */ rc = PsnsPurgeFiles( handle); if( rc) { printf( "PsnsPurgeFiles returned %d", rc); return rc; } /* add a single file to the list */ rc = PsnsAddFile( handle, "D:\\Setup.cmd", 0); if( rc) { printf( "PsnsAddFile returned %d", rc); return rc; } /* add a directory and its contents */ rc = PsnsAddFile( handle, "D:\\Data\\", 0); if( rc) { printf( "PsnsAddFile returned %d", rc); return rc; } /* add a directory and all files & directories beneath it */ rc = PsnsAddFile( handle, "D:\\Code\\*\\", 0); if( rc) { printf( "PsnsAddFile returned %d", rc); return rc; } /* Fill in some details for the backup method */ strcpy( backupMethodInfo.backupSet, "Project Llama"); backupMethodInfo.compression = PSNS_COMPRESSION; backupMethodInfo.generations = 8; backupMethodInfo.changedFilesOnly = FALSE; /* back up the files */ rc = PsnsBackupFiles( handle, &backupMethodInfo, fnCallBack); if( rc) { printf( "PsnsBackupFiles returned %d", rc); return rc; } return PSNS_OK; ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsPurgeFiles */ /* PsnsAddFile */ /* PsnsRestoreFiles */ /* */ /* Restore a selection of files */ /****************************************************/ int rc; RESTOREMETHODINFO restoreMethodInfo; /* empty the file list for this handle */ rc = PsnsPurgeFiles( handle); if( rc) { printf( "PsnsPurgeFiles returned %d", rc); return rc; } /* add a single file to the list */ rc = PsnsAddFile( handle, "D:\\Setup.cmd", 0); if( rc) { printf( "PsnsAddFile returned %d", rc); return rc; } /* add a directory and its contents */ rc = PsnsAddFile( handle, "D:\\Data\\", 0); if( rc) { printf( "PsnsAddFile returned %d", rc); return rc; } /* add a directory and all files & directories beneath it */ rc = PsnsAddFile( handle, "D:\\Code\\*\\", 0); if( rc) { printf( "PsnsAddFile returned %d", rc); return rc; } /* Fill in some details for the restore method */ strcpy( restoreMethodInfo.backupSet, "Project Llama"); /* restore the files */ rc = PsnsRestoreFiles( handle, &restoreMethodInfo, fnCallBack); if( rc) { printf( "PsnsRestoreFiles returned %d", rc); return rc; } return PSNS_OK; ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsGetBackupSetConfig */ /* PsnsSetBackupSetConfig */ /* */ /* Make sure an optical backup set doesn't play a */ /* sound when requesting a volume */ /****************************************************/ int quieten_backupset( PSNSHANDLE handle, const char *backupset) { int rc = PSNS_OK; char *string; ULONG cbString, cbStringInc; /* find out how large a buffer is needed */ rc = PsnsGetBackupSetConfig( handle, backupset, NULL, &cbString, NULL, NULL); if( rc) return rc; string = malloc( cbString); /* query the configuration string */ rc = PsnsGetBackupSetConfig( handle, backupset, string, &cbString, NULL, NULL); if( !rc && strstr( string, "BEEP=YES")) /* turn beeping off */ rc = PsnsSetBackupSetConfig( handle, backupset, "BEEP=NO", NULL); free( string); return rc; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsGetStorageDeviceConfig */ /* */ /* Print out the letter of the hard drive used by */ /* the device for storing backed up data. */ /****************************************************/ int print_path( PSNSHANDLE handle, const char *device) { int rc = PSNS_OK; char *string; ULONG cbString; /* find out how large a buffer is needed */ rc = PsnsGetStorageDeviceConfig( handle, device, 0, &cbString); if( rc) return rc; string = malloc( cbString); /* query the configuration string */ rc = PsnsGetStorageDeviceConfig( handle, device, string, &cbString); if( !rc) { char strDrive[] = "DRIVE="; /* find the `drive' keyword */ char *letter = strstr( string, strDrive) + strlen( strDrive); printf( "%s uses drive %c\n", device, *letter); } free( string); return rc; } ═══ Example ═══ /****************************************************/ /* Functions used: */ /* PsnsSetStorageDeviceConfig */ /* */ /* Update the location of the ADSM options file. */ /****************************************************/ int rc; rc = PsnsSetStorageDeviceConfig( handle, "ADSM", "OPTFILE=E:\\DSM.OPT"); if( rc) printf( "PsnsSetStorageDeviceConfig returned %d\n", rc); ═══ Example ═══ This example hasn't been written yet. ═══ 6. Backup methods ═══ The main way to back up files with OS/2 Warp Server Backup/Restore is by using backup methods. A backup method tells OS/2 Warp Server Backup/Restore which files you want to back up, how you want to back them up and to where you want to back them up. The following sections tell you how to create, manipulate and run backup methods.  Working with backup methods  Running and estimating backup methods ═══ 6.1. Working with backup methods ═══ You can create a backup method using the C API by calling the function PsnsCreateBackupMethod. This creates a new backup method with the given name. The backup method is created with default settings; you should change these with PsnsBackupMethodInfo to make the backup method perform the task you want. To rename, copy and delete backup methods, use the functions PsnsRenameBackupMethod, PsnsCopyBackupMethod and PsnsDeleteBackupMethod. To see the full range of settings which can be changed for a backup method and descriptions of what they do, see the BACKUPMETHODINFO structure. To inspect or change the settings, use the function PsnsBackupMethodInfo. This function takes as arguments a backup method name, a pointer to a BACKUPMETHODINFO structure and an integer mask. This mask controls which of the backup method settings are changed: to change all of the settings, use BM_ALL; to change none of the settings but just inspect the current ones, use BM_NONE. To change some combination of different settings, use the logical OR operator to combine several mask values. For more information, see PsnsBackupMethodInfo. To list backup methods or search for backup methods which match certain criteria, use PsnsListBackupMethods. This works in the same way as all the other API listing functions. ═══ 6.2. Running and estimating backup methods ═══ The main way to back up files with OS/2 Warp Server Backup/Restore is by running a backup method. To do this, use the function PsnsRunBackupMethod. This function takes as arguments the name of the backup method and a pointer to a callback function. As the backup progresses, there will be some information which OS/2 Warp Server Backup/Restore would like to communicate to the user about which object is currently being backed up and statistics about the numbers of files, folders and bytes which have been backed up successfully. You can supply PsnsRunBackupMethod with a pointer to a callback function, which should be of type PSNSSTATSFN. The callback function takes two arguments: the first is a pointer to a PSNSSTATS structure, which contains information about files, folders and bytes processed, as well as time taken, estimated total time, average data rate and space left on the backup media. If this pointer is NULL then there is no updated statistics information to be displayed. The second argument is a pointer to a text message which may contain the name of an object being currently backed up, or else a progress message such as "Rewinding tape". If this is NULL then there is no message to be displayed. To get information about how many files and folders would be backed up by a backup method but without actually running the backup, use PsnsEstimateBackupMethod. This tells OS/2 Warp Server Backup/Restore to scan the source drives and work out which files need to be backed up, and then return the results in an ESTIMATE structure, along with the estimated time for the backup, based on performance in previous backups to the same storage device. Note that the first time you use a storage device, the estimated time will be 0 since there are no previous backups on which to base the estimate. ═══ 7. Restore methods ═══ The main way to restore files with OS/2 Warp Server Backup/Restore is by using restore methods. A backup method tells OS/2 Warp Server Backup/Restore which files you want to restore, to where you want to restore them, and how to choose which generation will be restored. The following sections tell you how to create, manipulate and run restore methods.  Working with restore methods  Running and estimating restore methods ═══ 7.1. Working with restore methods ═══ You can create a restore method using the C API by calling the function PsnsCreateRestoreMethod. This creates a new restore method with the given name. The restore method is created with default settings; you should change these with PsnsRestoreMethodInfo to make the restore method perform the task you want. To rename, copy and delete restore methods, use the functions PsnsRenameRestoreMethod, PsnsCopyRestoreMethod and PsnsDeleteRestoreMethod. To see the full range of settings which can be changed for a restore method and descriptions of what they do, see the RESTOREMETHODINFO structure. To inspect or change the settings, use the function PsnsRestoreMethodInfo. This function takes as arguments a restore method name, a pointer to a RESTOREMETHODINFO structure and an integer mask. This mask controls which of the restore method settings are changed: to change all of the settings, use RM_ALL; to change none of the settings but just inspect the current ones, use RM_NONE. To change some combination of different settings, use the logical OR operator to combine several mask values. For more information, see PsnsRestoreMethodInfo. To list restore methods or search for restore methods which match certain criteria, use PsnsListRestoreMethods. This works in the same way as all the other API listing functions. ═══ 7.2. Running and estimating restore methods ═══ The main way to restore files with OS/2 Warp Server Backup/Restore is by running a restore method. To do this, use the function PsnsRunRestoreMethod. This function takes as arguments the name of the restore method and a pointer to a callback function. As the restore progresses, there will be some information that OS/2 Warp Server Backup/Restore would like to communicate to the user about which file is currently being restored and statistics about the numbers of files, folders and bytes which have been restored successfully. You can supply PsnsRunRestoreMethod with a pointer to a callback function, which should be of type PSNSSTATSFN. The callback function takes two arguments: the first is a pointer to a PSNSSTATS structure, which contains information about files, folders and bytes processed, as well as time taken, estimated total time and average data rate. If this pointer is NULL then there is no updated statistics information to be displayed. The second argument is a pointer to a text message which may contain the name of a file being currently backed up, or else a progress message such as "Rewinding tape". If this is NULL then there is no message to be displayed. To get information about how many files and folders would be restored by a restore method but without actually running the restore, use PsnsEstimateRestoreMethod. This tells OS/2 Warp Server Backup/Restore to scan the backup set and work out which files would need to be restored, and then return the results in a ESTIMATE structure, along with the estimated time for the restore, based on performance in previous restores to the same storage device. Note that the first time you use a storage device, the estimated time will be 0 since there are no previous restores on which to base the estimate. ═══ 8. Backup sets ═══ A backup set is where data is stored by OS/2 Warp Server Backup/Restore A backup set is associated with a particular storage device and may contain more than one physical volume of backed-up data. The following section tell you how to create and manipulate backup sets.  Working with backup sets ═══ 8.1. Working with backup sets ═══ You can create a backup set with the C API by calling the function PsnsCreateBackupSet. You must specify a storage device with which to associate the backup set. The backup set is created with a default configuration, which should in most cases be sufficient. To delete a backup set, use PsnsDeleteBackupSet. Note: When you delete a backup set, all backed-up data on it is lost! To empty the backup set of data without deleting the backup set itself, use PsnsEmptyBackupSet. To change the description of a backup set, or to inspect the description and find out which storage device it is associated with, use PsnsBackupSetInfo. This function takes as arguments a backup set name, a pointer to a BACKUPSETINFO structure and an integer mask. Currently there are only two useful values for the mask: BS_DESCRIPTION to set the description of the backup set, or BS_NONE to inspect the current settings. Other backup set settings depend on the storage device which the backup set uses, and so are set and queried using a configuration string. Use the functions PsnsGetBackupSetConfig and PsnsSetBackupSetConfig to get and set the configuration string for a backup set. For more information, see Storage Device configuration. To list backup sets or search for backup sets which match certain criteria, use PsnsListBackupSets. This works in the same way as all the other API listing functions. Backup sets can be transferred out, which means that OS/2 Warp Server Backup/Restore writes all index data to the backup set media and then will not use the backup set for any more backups or restores until it is transferred in again. This is useful, for example, for moving backup sets between machines. To transfer a backup set in or out, use PsnsTransferBackupSet. This function takes as arguments the name of the backup set and a flag specifying whether the backup set is to be transferred in or out. Each backup set has a log file which is a text file containing a log of activity performed on that backup set. To find the name of the log file for a backup set, use the function PsnsGetLogFile. You can then, for example, view, process or delete the log file. Dual device backup sets can be also be created with the PsnsCreateBackupSet function. These allow you to perform an initial backup to one storage device, then further backups to an incremental device. The storage device to which you perform the initial backup is known as the base device. You may specify the virtual device only as the base storage device of a dual device backup set. ═══ 9. Storage devices ═══ Storage devices are the physical systems OS/2 Warp Server Backup/Restore uses to store backed-up data, such as tape drives, hard disks or ADSM servers. The following sections tell you how to create and manipulate storage devices.  Creating a storage device  Working with storage devices ═══ 9.1. Creating a storage device ═══ When a new storage device is created, it must be one of a number of available types; these are the names which appear when you select 'New' from the pop-up menu in the Storage Devices container in the OS/2 Warp Server Backup/Restore user interface. To accomplish this using the API, you can find out the available types of storage devices to create by calling PsnsListStorageDevices with the SD_CREATABLE bit set in the mask. This will list all creatable storage devices You can then call PsnsCreateStorageDevice which takes as an argument the name of the creatable storage device from which to create the new storage device. You must also specify a configuration string when you create a storage device, since there are some configuration options which can only be specified when a device is created and cannot be changed afterwards; for more information see Storage Device configuration. ═══ 9.2. Working with storage devices ═══ Storage device settings depend on the individual storage device, so they are set using a configuration string. For more information on configuration strings, see Storage Device configuration. Use the functions PsnsGetStorageDeviceConfig and PsnsSetStorageDeviceConfig to get and set the storage device configuration. To find out which Dynamic Link Library (DLL) file a storage device uses, call PsnsStorageDeviceInfo. This function takes as arguments the name of a storage device and a pointer to a STORAGEDEVICEINFO structure which is filled in with the name of the DLL. To list storage devices or search for storage devices which match certain criteria, use PsnsListStorageDevices. This works in the same way as all the other API listing functions. OS/2 Warp Server Backup/Restore usually scans for new storage devices automatically when it is started up. To perform this task manually, use the function PsnsRefreshStorageDevices. ═══ 10. Volumes ═══ Volumes are the individual tapes, diskettes or cartridges on which backed-up data is stored. OS/2 Warp Server Backup/Restore keeps track of which files are stored on which volumes, and how much space is used up on each volume; this means that the user does not have to worry about remembering exactly where their data is. The following section tells you how to create and manipulate volumes.  Working with volumes ═══ 10.1. Working with volumes ═══ Volumes are referred to by their volume ID, which is an unsigned long integer. Creating a volume involves formatting and labelling the volume. Before you can create a volume using the API, you should ensure that the correct tape or diskette is already in the drive. When creating a volume under the graphical environment, the user is asked to insert the correct tape or diskette before formatting, but since this cannot be done when running under the API it is assumed that the correct media is already in the drive. To create a volume, call the function PsnsCreateVolume. Note: Creating a volume will erase all data from the media currently in the drive. You should not have an existing volume in the drive when you call this function; always empty the backup set or delete the volume if you wish to re-use it. To delete a volume, use the function PsnsDeleteVolume. This will make OS/2 Warp Server Backup/Restore forget about all backed-up data on the volume. You should not use this function as a regular part of your storage management, but only in circumstances such as when you have lost a tape and want to let OS/2 Warp Server Backup/Restore know this. To get information about a volume, use PsnsVolumeInfo. This takes as arguments a volume ID and a pointer to a VOLUMEINFO structure. Information about the volume and its space usage is returned in the structure. To list volumes and to list backup sets on a volume, use the functions PsnsListVolumes and PsnsListVolumeBackupSets. These work in the same way as the other API listing functions. It is possible to deactivate a volume; in this state, the volume will not be used for backups or restores. You could do this if the volume is unavailable and you do not want OS/2 Warp Server Backup/Restore to request it when performing a backup. To deactivate or activate a volume, use the function PsnsActivateVolume. When a volume is first created, it is not associated with any particular backup set and so will not be used for backup. Before the volume can be used, you must associate it with a backup set; this can be done with the API by calling PsnsAssociateVolume. ═══ 11. Events ═══ OS/2 Warp Server Backup/Restore allows you to schedule events which will run a backup method at a particular time. The following section tells you how to create and manipulate scheduled events.  Working with events ═══ 11.1. Working with events ═══ There are five different types of scheduled events in OS/2 Warp Server Backup/Restore:  Interval or regular events. These events happen at regular intervals in time, for example every hour or every ten minutes.  Daily events. These happen at a certain time each day.  Monthly events. These happen at a certain time on a certain day of each month.  Named day(s) events. These happen at a certain time on some days of each month. You can select individually on which days of the week and in which weeks of the month the event will occur.  Startup events. These occur a fixed time after starting up OS/2 Warp Server Backup/Restore. Events are referred to by an event ID, which is an unsigned short integer. They do not have names. To create an event, call PsnsCreateEvent. You must specify the type of the event and the name of a backup method. The backup method can be changed later but you must supply one when creating an event since there is no sensible default option. A new event ID will be created and returned. To delete an event, use PsnsDeleteEvent. To copy an event, use PsnsCopyEvent. A new event ID will be created and returned. The information about an event is contained in the EVENTINFO structure. This contains a union which has a member for each different type of event. Remember that you should only use one member of a union at a time; the other members will be meaningless. To get or set the information about an event, use PsnsEventInfo. This function takes as arguments an event ID, a pointer to an EVENTINFO structure and an integer mask. This mask controls which of the event settings are changed: to change all of the settings, use EV_ALL; to change none of the settings but just inspect the current ones, use EV_NONE. To change some combination of different settings, use the logical OR operator to combine several mask values. For more information, see PsnsEventInfo. To list events and search for events which match certain criteria, use PsnsListEvents. This works in the same way as the other API listing functions. Note that if you want to search on any of the fields which are particular to one type of event (such as, which day of the month), you must specify a type of event to search for as well. To find out which event is due to occur next, use PsnsGetNextEvent. Events can be deactivated so that they will not occur; for example, you may want to deactivate a regular backup during a holiday or during system maintenance. To activate or deactivate an event, use the function PsnsActivateEvent. ═══ 12. File filters ═══ File filters allow you to automatically select files to be backed up. The following section tells you how to create and manipulate file filters.  Working with file filters  Working with file filter rules ═══ 12.1. Working with file filters ═══ In the OS/2 Warp Server Backup/Restore graphical user interface, there are two types of file filters: tree-based and rule-based filters. In fact all file filters are stored internally as rule-based filters, so this is how they are accessed using the API. To create a file filter, use the function PsnsCreateFileFilter. You must specify a name for the file filter and the type of the filter. The type you specify only changes how the file filter is edited under the graphical user interface; it does not alter how the file filter appears under the API. The file filter is created with one rule in it; this is the 'last' rule which matches all files not matched by any other rules. To delete, rename and copy file filters, use the functions PsnsDeleteFileFilter, PsnsRenameFileFilter and PsnsCopyFileFilter. The settings for the file filter are contained in a FILEFILTERINFO structure. The only settings you can change are the type and the description of the file filter. To inspect or change the settings, use the function PsnsFileFilterInfo. This function takes as arguments a file filter name, a pointer to a FILEFILTERINFO structure and an integer mask. This mask controls which of the file filter settings are changed: to change all of the settings, use FF_ALL; to change none of the settings but just inspect the current ones, use FF_NONE. To change some combination of different settings, use the logical OR operator to combine several mask values. For more information, see PsnsFileFilterInfo. To list file filters and search for file filters which match certain criteria, use PsnsListFileFilters. This works in the same way as the other API listing functions. You can also ask to search for all file filters which would select a certain file. ═══ 12.2. Working with file filter rules ═══ Information about a file filter rule is kept in a FILEFILTERRULE structure. A file filter rule specifies which files it matches and whether they should be included or excluded from the backup. When a file is tested to see whether it should be backed up or not, it is matched against all of the rules in turn, starting from the first one. When a rule is found which matches the file, that rule is used to decide whether the file should be backed up or not. Every file filter contains one rule, which is always last, which matches all files not selected by any other rules. You cannot delete this rule or change it except to change whether the files are to be included or excluded. To add a rule to a file filter, use PsnsAddFileFilterRule. This takes as arguments the name of a file filter, a pointer to a FILEFILTERRULE structure, and an integer which specifies where in the file filter the rule is to be added; use 1 to add the rule at the top of the list of rules in the file filter, 2 to add it in second place and so on. To delete a rule from a file filter, use PsnsDeleteFileFilterRule. You cannot delete the 'last' rule in a file filter. To inspect or change the settings for a file filter rule, use the function PsnsFileFilterRuleInfo. This function takes as arguments a file filter name, a pointer to a FILEFILTERRULE structure and an integer mask. This mask controls which of the file filter settings are changed: to change all of the settings, use FF_ALL; to change none of the settings but just inspect the current ones, use FF_NONE. To change some combination of different settings, use the logical OR operator to combine several mask values. For more information, see PsnsFileFilterRuleInfo. ═══ 13. Rulebooks ═══ Rulebooks allow you to use rules to decide how many generations of a file should be backed up and whether or not compression should be used. The following section tells you how to create and manipulate rulebooks.  Working with rulebooks  Working with rulebook rules ═══ 13.1. Working with rulebooks ═══ To create a rulebook, use the function PsnsCreateRulebook. The rulebook is automatically created with one rule in it which is always kept as the 'last' rule in the rulebook. It specifies how to back up files not matched by any of the preceding rules and cannot be deleted but its backup attributes can be modified. To delete, rename and copy rulebooks, use the functions PsnsDeleteRulebook, PsnsRenameRulebook and PsnsCopyRulebook. The settings for the rulebook are contained in a RULEBOOKINFO structure. The only setting you can change is the description of the rulebook. To inspect or change the settings, use the function PsnsRulebookInfo. This function takes as arguments a rulebook name, a pointer to a RULEBOOKINFO structure and an integer mask. This mask controls which of the rulebook settings are changed: to change the setting, use RB_ALL; to change none of the settings but just inspect the current ones, use RB_NONE. For more information, see PsnsRulebookInfo. To list rulebooks and search for rulebooks which match certain criteria, use PsnsListRulebooks. This works in the same way as the other API listing functions. ═══ 13.2. Working with rulebook rules ═══ Information about a rulebook rule is kept in a RULEBOOKRULE structure. A rulebook rule specifies which files it matches, how many generations to keep and whether or not compression should be performed on the files. When a file is to be backed, it is compared with all of the rules in turn, starting from the first one. When a rule is found which matches the file, that rule is used to decide the number of generations and compression to use for that file. Every rulebook contains one rule, which is always last, which matches all files not selected by any other rules. You cannot delete this rule or change it except to change the number of generations and compression. To add a rule to a rulebook, use PsnsAddRulebookRule. This takes as arguments the name of a rulebook, a pointer to a RULEBOOKRULE structure, and an integer which specifies where in the rulebook the rule is to be added; use 1 to add the rule at the top of the list of rules in the rulebook, 2 to add it in second place and so on. To delete a rule from a rulebook, use PsnsDeleteRulebookRule. You cannot delete the 'last' rule in a rulebook. To inspect or change the settings for a rulebook rule, use the function PsnsRulebookRuleInfo. This function takes as arguments a rulebook name, a pointer to a RULEBOOKRULE structure and an integer mask. This mask controls which of the rulebook settings are changed: to change all of the settings, use RB_ALL; to change none of the settings but just inspect the current ones, use RB_NONE. To change some combination of different settings, use the logical OR operator to combine several mask values. For more information, see PsnsRulebookRuleInfo. ═══ 14. Source drives ═══ OS/2 Warp Server Backup/Restore keeps a list of all drives on your system to decide where it should look for files to back up. The following section tells you how to manipulate source drives.  Working with source drives ═══ 14.1. Working with source drives ═══ OS/2 Warp Server Backup/Restore keeps a list of all drives on your system. When you do a backup which specifies that files should be backed up from all drives, this list is used to decide which drives should be checked for files to back up. For example, you might want to back up files from your local hard disks but not from your network drives. Information about source drives is contained in a SOURCEDRIVEINFO structure. To list all the source drives which OS/2 Warp Server Backup/Restore knows about, use PsnsListSourceDrives. This works in the same way as the other API listing functions. To select or deselect a source drive for backup, use PsnsSelectSourceDrive. When you start up OS/2 Warp Server Backup/Restore, it scans to see which drives are attached to your system. To do this again manually, use the function PsnsRefreshSourceDrives. To change the type of a source drive if it has been incorrectly detected, use PsnsSourceDriveType. ═══ 15. Files ═══ The following two sections tell you about dealing with individual files.  Working with backed-up data  Working with lists of individual files ═══ 15.1. Working with backed-up data ═══ Data is stored in a backup set as a series of generations of files. Each time you back up a file, a new generation is created, and an old generation might be dropped. To list generations which are backed up to a backup set, use PsnsListFiles. This function has two modes of operation: you can list files which match certain criteria, in which case only one generation of each file will be listed, and it will be the one which best matches the criteria; or you can list all generations which match the criteria by setting the FILE_ALLGENERATIONS bit in the mask. For more information, see listing functions. While you are listing backed-up data, you cannot perform any other operations on the backup set; you must wait until the listing operation is finished. To remove files from the backup set, use PsnsDropFiles. ═══ 15.2. Working with lists of individual files ═══ In addition to backing up and restoring files using backup methods and restore methods, it is also possible to back up or restore a specific list of files; this is useful for working with individual files on a one-off basis. If, however, you plan to back up or restore the same files regularly, you should use a backup or restore method. To perform operations on a list of files, you must first tell OS/2 Warp Server Backup/Restore which files you want to work on. To do this, call PsnsAddFile once for every file or group of files you want to add to the list. This does not actually do anything to the files, it simply remembers them. Afterwards, use PsnsBackupFiles, PsnsRestoreFiles or PsnsDropFiles to work with the files. To empty the list without performing any operations on the files, use PsnsPurgeFiles. ═══ 16. Listing functions ═══ There are many functions in the OS/2 Warp Server Backup/Restore API for listing objects of various sorts. They all work in a similar way:  Each listing function has a handle which is of type HPSNSLIST. This handle is used to identify the listing operation between calls. The first time you call a listing function, you should set the handle to 0 and pass a pointer to it to the listing function. On return from the listing function, the handle will have been set to a new value (unless there are no items to list). You should then keep passing a pointer to the same handle on each subsequent call to the listing function, so that the next object can be returned on each call. When you have listed all the objects, the handle will be set back to 0 to indicate that there are no more objects to list.  The other arguments to the listing functions are a pointer to a structure, and a mask. The first time you call the listing function, with the handle set to 0, the structure should contain the criteria you want to search on, and the mask should indicate which fields in the structure you want to search on. On the first call to the listing function, the search criteria from the structure and the mask are stored internally and the structure is used to return the first object found. On subsequent calls, the contents of the structure are overwritten with the details of the next object found.  When the last object is listed the listing operation is automatically stopped, the handle freed and any resources deallocated. However, if you want to stop listing objects before you get to the last one, that is, while the handle is still non-zero, you should use PsnsCloseList to free the listing operation. ═══ 17. Object names ═══ Object names in OS/2 Warp Server Backup/Restore can contain any printable text character, except that:  They may not begin with a space  They may not begin with a < (less than) sign  They must be at least one character long ═══ 18. Wildcards ═══ Some fields, especially when searching for objects in OS/2 Warp Server Backup/Restore, may contain wildcards. When searching for object names and any other string apart from fully qualified filenames, the asterisk character (*) may be used to match any sequence of characters. In fully qualified filenames, wildcards may be used as follows:  The drive letter may be *, which means look for files on all drives.  The path may end with \*\, meaning look in all subdirectories of the named directory.  The filename may contain one or more asterisks (*) which act as usual wildcards. ═══ 19. Storage device and backup set configuration ═══ The configuration of storage devices and backup sets is done by means of configuration strings, the contents of which are specific to the storage device. A configuration string consists of a series of keywords and values, separated by semicolons (;), for example: BEEP=YES;VERIFY=NO; The caret (^) can be used as an escape character if either semicolons or equals signs are required in a value. A value may also be enclosed in either single or double quotation marks; the caret can be used as an escape character if a quotation mark is required within a quoted string. A value must be enclosed in quotation marks if leading or trailing space characters are required. In order to include a caret in a value, 2 consecutive caret characters should be used. Storage devices require a configuration string when they are created with PsnsCreateStorageDevice; once created, their configuration string can be obtained with PsnsGetStorageDeviceConfig. Some storage devices, for example the ADSM device, can be reconfigured, using PsnsSetStorageDeviceConfig. It is possible to supply a configuration string when creating a backup set using PsnsCreateBackupSet, but this is optional. Once created, a backup set's configuration string can be obtained with PsnsGetBackupSetConfig; backup sets on some types of storage device may be reconfigured using PsnsSetBackupSetConfig. The following sections describe the format of configuration strings for the standard storage devices. ═══ 19.1. SCSI tape storage devices ═══ These sections describe configuration strings for SCSI tape storage devices and backup sets. ═══ 19.1.1. Storage device configuration ═══ The following keywords are supported: ADAPTER Meaning The number of the SCSI adapter to which the tape drive is attached. Valid values A valid SCSI adapter number. This keyword must be supplied when creating a storage device. PUN Meaning The SCSI Physical Unit Number (PUN) of the tape drive. Valid values A valid PUN. This keyword must be supplied when creating a storage device. For example: PsnsCreateStorageDevice( handle, "Tape", "ADAPTER=2;PUN=3;", newname); SCSI tape storage devices cannot be reconfigured. ═══ 19.1.2. Backup set configuration ═══ The following keywords are supported: CHECKDRIVE Meaning If you select this option then OS/2 Warp Server Backup/Restore will check the drive for a suitable volume before it prompts you to insert a tape. This option is useful when you are performing unattended backups. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, the user will always be prompted to insert a tape, even if the required volume is already in the drive. BEEP Meaning Whether OS/2 Warp Server Backup/Restore should make a noise when it asks for a tape volume to be inserted. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, a noise will not be made. For example: PsnsSetBackupSetConfig( handle, bksName, "CHECKDRIVE=YES;BEEP=NO;"); SCSI tape backup sets can be reconfigured. ═══ 19.2. Diskette and RW optical storage devices ═══ These sections describe configuration strings for diskette and RW optical storage devices and backup sets. ═══ 19.2.1. Storage device configuration ═══ The following keywords are supported: DRIVE Meaning The letter of the drive which the storage device is to use for backup Valid values A drive letter. This keyword must be supplied when creating a storage device. INDEXDRIVE (Optical only) Meaning The letter of the drive to which the storage device backs up index files. Valid values A diskette drive letter. This keyword is optional when creating a storage device. If it is absent, drive A will be used. For example: PsnsCreateStorageDevice( handle, "RW Optical", "DRIVE=F;INDEXDRIVE=A", newname); Diskette and RW optical storage devices cannot be reconfigured. ═══ 19.2.2. Backup set configuration ═══ The following keywords are supported: BACKUPINDEX Meaning Whether OS/2 Warp Server Backup/Restore should automatically back up its index files using index diskettes. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, index files will be backed up. BEEP Meaning Whether OS/2 Warp Server Backup/Restore should make a noise when it asks for a diskette or RW optical disk to be inserted. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, a noise will be made. VERIFY Meaning Whether OS/2 Warp Server Backup/Restore should confirm that the data written to diskette or RW optical disk is correct. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, backups will be verified. For example: PsnsSetBackupSetConfig( handle, bksName, "BEEP=NO;VERIFY=YES"); Diskette and RW optical backup sets can be reconfigured. ═══ 19.3. ADSM storage devices ═══ These sections describe configuration strings for ADSM storage devices and backup sets. Note: ADSM storage devices cannot be created using PsnsCreateStorageDevice. Instead, one is automatically created on installation, and this can then be edited if necessary. ═══ 19.3.1. Storage device configuration ═══ The following keywords are supported: OPTIONSFILE Meaning The name of the ADSM options file to be used when connecting to the ADSM server, or the name of the file to be used to set the initial values for the ADSM options file when the NEWOPTIONSFILE keyword is also specified. The ADSM options file must exist and contain valid options before a connection with the ADSM server may be successfully established. The options file may be updated using special keywords in the configuration string. Valid values The name of an existing ADSM options file. This keyword is optional. If it is absent when creating the storage device, a default file name will be used, if it is absent when updating the storage device, the name of the options file will not be changed. NEWOPTIONSFILE Meaning The name of the ADSM options file to be used when connecting to the ADSM server. The file will be created if it does not already exist; any existing file of the same name will be replaced. The initial option values for the new options file depend on the value of the OPTIONSFILE keyword: OPTIONSFILE=filename The initial values will be taken from filename. OPTIONSFILE= There will be no initial values. OPTIONSFILE not specified The initial values will be taken from the options file specified in the existing ADSM storage device settings. Values in the options file may be set or updated using special keywords in the configuration string. Valid values A valid file name. This keyword is optional. If it is absent, the name of the ADSM options file to be used is determined by the value of the OPTIONSFILE keyword and no new options file will be created. NODENAME Meaning The node name to be used for connection to the ADSM server. Valid values A valid ADSM node name; this node name must be registered at the ADSM server before a connection may be successfully established. This keyword is optional. If it is absent when creating the storage device, a default node name will be used, if it is absent when updating the storage device, the node name will not be changed. MGMTCLASS Meaning This is the ADSM management class to be used for backing up objects from OS/2 Warp Server Backup/Restore. This management class must be known at the ADSM server to which you will connect, and must be defined within the active policy set of the policy domain which is associated with your node. If you do not specify a management class, or if the management class is not defined within your active policy set, the default management class for your node will be used. If you set the management class to be mgmt_class, a statement of the form: INCLUDE * mgmt_class is inserted into your ADSM options file. Valid values A valid ADSM management class name. This keyword is optional. If it is absent when creating the storage device, the default management class for your node will be used, if it is absent when updating the storage device, the management class name will not be changed. MAXOBJECTS Meaning When OS/2 Warp Server Backup/Restore is backing up objects to an ADSM server, several objects may be sent to ADSM in a single batch; each batch is a single ADSM transaction. Each object (file or directory) that you back up using OS/2 Warp Server Backup/Restore may actually be stored in ADSM as several ADSM objects. For example, if a file has extended attributes, the file and its extended attributes may actually be stored as two separate ADSM objects. You can use this setting to limit the number of OS/2 Warp Server Backup/Restore objects that are included in a batch (the corresponding number of ADSM objects may be greater). Note: ADSM also has a limit on the number of its objects that can be stored in a single transaction. The number of OS/2 Warp Server Backup/Restore objects actually sent in a batch will be less than the number specified by MAXOBJECTS if the corresponding number of ADSM objects to be stored exceeds the limit set by ADSM. Valid values A non-zero numeric value. This keyword is optional. If it is absent when creating the storage device, a default value will be used, if it is absent when updating the storage device, the setting will not be changed. PASSWORDLIFE Meaning If a password is required to access the services of ADSM, OS/2 Warp Server Backup/Restore will prompt you to enter your password the first time you attempt to use the services of ADSM in each use of OS/2 Warp Server Backup/Restore. If you use the services of ADSM more than once in a single use of OS/2 Warp Server Backup/Restore, OS/2 Warp Server Backup/Restore will not ask you to enter your password again until the number of minutes specified by PASSWORDLIFE has passed. Valid values A non-zero numeric value. This keyword is optional. If it is absent when creating the storage device, a default value will be used, if it is absent when updating the storage device, the setting will not be changed. PASSWORDPROMPT Meaning Whether OS/2 Warp Server Backup/Restore should prompt for entry of the ADSM password when connecting to the ADSM server during unattended operation. Note: If entry of the ADSM password is required during unattended operation and password prompting has been suppressed (PASSWORDPROMPT=NO), the operation will fail. The requirement for entry of the ADSM password can be avoided by using the option 'PASSWORDACCESS GENERATE' in the ADSM options file, or by setting the ADSM password by use of the PASSWORD keyword in the ADSM storage device configuration string. Valid values YES or NO This keyword is optional. If it is absent when creating the storage device, prompting for the ADSM password during unattended operation will not be suppressed, if it is absent when updating the storage device, the setting will not be changed. PASSWORD Meaning This keyword may be used to set the ADSM password for the current execution of the API server; the value will not be retained for future invocations of the server. Valid value The correct password for the ADSM node name associated with the ADSM storage device. This keyword is optional. If it is absent, no password will be set. NEWPASSWORD Meaning This keyword may be used to change the ADSM password. Note: The current password must also be specified by the PASSWORD keyword, unless the option 'PASSWORDACCESS GENERATE' is included in the ADSM options file and the current password is stored locally by ADSM (in encrypted form). Valid value A valid ADSM password. This keyword is optional. If it is absent, the password will not be changed. CONNECT Meaning Whether OS/2 Warp Server Backup/Restore should test the connection to the ADSM server. Valid values YES or NO This keyword is optional. If it is absent, the connection to the ADSM server will not be tested. For example: PsnsSetStorageDeviceConfig ( handle, "ADSM", "OPTIONSFILE=C:\\ADSM\\DSM.OPT;NODENAME=PSNSclient", newname); ═══ 19.3.2. Updating the ADSM options file ═══ The ADSM storage device configuration string can contain special keywords (In addition to the standard OS/2 Warp Server Backup/Restore configuration string syntax) in order to add, change or delete options in the ADSM options file. ADSM options may be added or changed by including specifications of the form: +option value where: option is the name of an ADSM option to be added to, or changed in the ADSM options file. value is the value to be set for the ADSM option. or: -option where: option is the name of an ADSM option to be deleted from the ADSM options file. Note: No validation of the ADSM option name or value is performed. For example: PsnsSetStorageDeviceConfig ( handle, "ADSM", "OPTIONSFILE=C:\\ADSM\\DSM.OPT;" \ "NEWOPTIONSFILE=C:\\ADSM\\PSNS.OPT;" \ "-verbose; +quiet;" \ "+PASSWORDACCESS GENERATE;-PASSWORDDIR;" \ "+COMMMETHOD TCPIP;" \ "+TCPPort 1500;" \ "+TCPServeraddress n.n.n.n;" \ "+TCPBuffsize 8;" \ "+TCPWindowsize 16", newname); ═══ 19.3.3. Backup set configuration ═══ ADSM backup sets have no configurable settings. ═══ 19.4. Hard disk and remote disk storage devices ═══ These sections describe configuration strings for hard disk and remote disk storage devices and backup sets. ═══ 19.4.1. Storage device configuration ═══ DRIVE Meaning The letter of the drive which the storage device is to use for backup. Valid values A drive letter. This keyword must be supplied when creating a storage device. PATH Meaning The name of the directory in which the storage device will store backed up data. Valid values A valid directory name. This keyword is optional when creating a storage device. If it is absent, the directory PSNS5BKP will be used. For example: PsnsCreateStorageDevice( handle, "Hard Disk", "DRIVE=D;PATH=BACKUP", newname); Hard and remote disk storage devices cannot be reconfigured. ═══ 19.4.2. Backup set configuration ═══ The following keyword is supported: PATH Meaning The subdirectory of the storage device's directory in which the backup set will store data. Valid values A valid directory name. This keyword is optional when creating a backup set. If it is absent, a name will be generated from the name of the backup set. For example: PsnsCreateBackupSet( handle, bksName, devName, "PATH=LLAMA"); Hard and remote disk backup sets cannot be reconfigured. ═══ 19.5. LAN alias storage devices ═══ These sections describe configuration strings for LAN alias storage devices and backup sets. ═══ 19.5.1. Storage device configuration ═══ The following keywords are supported: SERVER Meaning The name of the LAN server on which the device is to store data. Valid values The name of a LAN server This keyword must be supplied when creating a storage device. ALIAS Meaning The name of the alias on the server in which the device is to store data. Valid values A LAN server alias. This keyword must be supplied when creating a storage device. PATH Meaning The name of the directory in which the storage device will store backed up data. Valid values A valid directory name. This keyword is optional when creating a storage device. If it is absent, the directory PSNS5BKP will be used. For example: PsnsCreateStorageDevice( handle, "Lan Drive", "SERVER=WDGSRV;ALIAS=PSNS", newname); LAN alias storage devices cannot be reconfigured. ═══ 19.5.2. Backup set configuration ═══ The following keyword is supported: PATH Meaning The subdirectory of the storage device's directory in which the backup set will store data. Valid values A valid directory name. This keyword is optional when creating a backup set. If it is absent, a name will be generated from the name of the backup set. For example: PsnsCreateBackupSet( handle, bksName, devName, "PATH=LLAMA"); LAN alias backup sets cannot be reconfigured. ═══ 19.6. Removable drive storage device ═══ These sections describe configuration strings for the removable drive storage device and backup sets. ═══ 19.6.1. Storage device configuration ═══ DRIVE Meaning The letter of the drive which the storage device is to use for backup. Valid values A drive letter. This keyword must be supplied when creating a storage device. PATH Meaning The name of the directory in which the storage device will store backed up data. Valid values A valid directory name. This keyword is optional when creating a storage device. If it is absent, the directory PSNS6BKP will be used. For example: PsnsCreateStorageDevice( handle, "Removable Drive", "DRIVE=D;PATH=BACKUP", newname); Removable Drive storage devices cannot be reconfigured. ═══ 19.6.2. Backup set configuration ═══ The following keywords are supported: BACKUPINDEX Meaning If you select this option, OS/2 Warp Server Backup/Restore will automatically back up its Index Files for the Backup Set every time you perform a backup. Warning: If the Back up index files option is not selected then no back ups are made of the Index Files. This is strongly discouraged, as it means your data will be impossible to retrieve if the Index Files on Hard Disk are lost. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, index files will be backed up. BEEP Meaning Whether OS/2 Warp Server Backup/Restore should make a noise when it asks for a removable drive to be inserted. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, a noise will be made. VERIFY Meaning Whether OS/2 Warp Server Backup/Restore should confirm that the data written to the removable drive is correct. Valid values YES or NO This keyword is optional when creating a backup set. If it is absent, backups will not be verified. For example: PsnsSetBackupSetConfig( handle, bksName, "BEEP=NO;VERIFY=YES"); Removable drive backup sets can be reconfigured. ═══ 19.7. Virtual storage device ═══ There are no configuration strings for the virtual storage device or backup sets.