Function 5F02h Get Assign-List Entry

mov bx, ListIndex ;assign-list index

mov si, seg LocalBuffer

mov ds, si

mov si, offset LocalBuffer ;ds:si points to buffer for local name

mov di, seg NetBuffer

mov es, di

mov di, offset NetBuffer ;es:di points to buffer for network name

mov ax, 5F02h ;Get Assign-List Entry

int 21h

jc error_handler ;carry set means error

Get Assign-List Entry (Function 5F02h) retrieves the local and network names of a device, such as a network printer. MS-DOS uses the assign-list index—which a program sets by using Make Assign-List Entry (Function 5F03h)—to search a list of network connections.

Parameters

ListIndex

Specifies the assign-list index for a network device.

LocalBuffer

Points to a 16-byte buffer that is to receive the local name of the device.

NetBuffer

Points to a 128-byte buffer that is to receive the network name of the device.

Return Value

If the function is successful, the carry flag is clear, the name buffers are filled in, the CX register contains the user value stored by Make Network Connection (Function 5F03h), and the BX register contains the device-status value. Otherwise, the carry flag is set and the AX register contains an error value, which may be one of the following:

Value

Name

0001h	ERROR_INVALID_FUNCTION
0012h	ERROR_NO_MORE_FILES

Comments

The network must be running and file sharing must be active for this function to operate successfully.

This function returns 0001h (ERROR_INVALID_FUNCTION) if the network is not running. The function returns 0002h (ERROR_NO_MORE_FILES) if the index specified in ListIndex is greater than the number of entries in the assign list.

The device-status value has the following format:

Register

Description

BH	Specifies whether the device is valid (BH contains 01h) or invalid (BH contains 00h).
BL	Specifies the type of device (03h = printer, 04h = drive).

MS-DOS maintains one assign-list entry for each of the currently connected network devices. As a program connects and disconnects network devices, MS-DOS adds and deletes entries from the list. Each entry receives an assign-list index. The assign-list indexes are zero-based and consecutive—the first network device to be connected receives index 0, the second receives index 1, and so on. When a program disconnects a network device, MS-DOS reindexes the entries so that the indexes remain consecutive. For example, if the first network device is disconnected, the second device receives index 0, the third receives index 1, and so on. To determine the current index for a device, a program typically retrieves assign-list entries for each index, starting with 0, until it matches either the user value returned in the CX register or the network name pointed to by the ES:DI registers.