DosFSAttach

Attaches or detaches a drive to or from a remote file system driver (FSD), or a pseudocharacter device name to or from a local or remote FSD.

Syntax

DosFSAttach(pszDevice, pszFilesystem, pData, cbData, flag);

Parameters

pszDevice (PSZ) - input 

Pseudocharacter or spool device name.

A drive designation or a pseudocharacter device name when flag is 0 or 1. A drive designation is an ASCIIZ string consisting of the drive name followed by a colon. If an attachment is successful, all requests to that drive are routed to the specified file-system driver. If a detachment is successful, the drive is removed from the system's name space.

pszDevice points to the name of a spooled device when flag is 2 or 3. The pszDevice format is the same as above. Requests to that name are not seen by the file-system driver.

A pseudocharacter device name (single file device) is an ASCIIZ string consisting of the file-name subdirectory \DEV\. All requests to that name are routed to the specified file-system driver after a successful attachment. A successful detachment removes the name from the system's name space.

pszFilesystem (PSZ) - input 

Pointer to the remote file-system driver name.

Address of the ASCIIZ name of the remote file-system driver that is to be attached to or detached from the device specified by pszDevice. For spooled objects, this pointer is set to 0. The pointer to pszFilesystem must be set to 0 when flag is 2 or 3.

pData (PVOID) - input 

Pointer to file-system driver or spooler data.

Address of the user-supplied file-system driver argument data area when flag is 0 or 1. The meaning of the data is specific to the file-system driver. pData contains contiguous ASCIIZ strings; the first word of the buffer contains the number of ASCIIZ strings. When flag is 2, pData points to the structure as follows:

• hNmPipe (USHORT) : Handle of named pipe opened by spooler
• cbSpoolObj (BYTE) : Length of name of spooler object (excluding NULL)
• szSpoolObj (UCHAR) : Name of spooler object

When flag is 3, pData is set to zero.

cbData (ULONG) - input 

The length, in bytes, of pData.

flag (ULONG) - input 

Type of operation to be performed.

Possible values shown in the following list:

FS_ATTACH Attach file server

FS_DETACH Detach file server

FS_SPOOLATTACH Register a spooler device

FS_SPOOLDETACH De-register a spooler device

Return Code

ulrc (APIRET) - returns

DosFSAttach returns one of the following values:

• 0 NO_ERROR
• 8 ERROR_NOT_ENOUGH_MEMORY
• 15 ERROR_INVALID_DRIVE
• 124 ERROR_INVALID_LEVEL
• 252 ERROR_INVALID_FSD_NAME
• 253 ERROR_INVALID_PATH

Remarks

The redirection of drive letters that represent local drives is not supported.

File-system drivers cannot use DosFSAttach to establish open connections that are not attached to a name in the system's name space. They must issue DosFSCtl for such purposes as optimizing UNC connections or establishing access rights. DosFSAttach creates attachments only to drives or devices in the system's name space.

Example Code

This example attaches a drive to a remote file system driver (FSD). Assume that the FSD does not require any user-supplied data arguments.

 #define INCL_DOSFILEMGR   /* File Manager values */
 #define INCL_DOSERRORS    /* DOS error values */
 #include <os2.h>
 #include <stdio.h>

int main(VOID) {

 PVOID   pvDataBuffer    = NULL;     /* Arguments for the file system driver */
 APIRET  rc              = NO_ERROR; /* Return code */

    rc = DosFSAttach("Q:",                   /* Drive letter */
                     "\\LAN\\LANTOOLS",      /* Remote file system driver */
                     pvDataBuffer,           /* User-supplied arguments */
                     0,                      /* No arguments supplied */
                     FS_ATTACH);             /* Attach to the file system */

    if (rc != NO_ERROR) {
        printf("DosFSAttach error: return code = %u\n", rc);
        return 1;
    }

    return NO_ERROR;
}

Related Functions

• DosFSCtl