The LDDRIVER understands all functioncodes normally available for disks. Some special functions are used to control the logical disk driver. When loaded as a tape (LMax) it will understand tape functioncodes. All functions assume that a channel has been assigned to the device on which to operate. One exception is the 'Connect' function which needs a channel to LDA0:. This will then create a new device (because LDA0: is a cloned device). A file with LDdriver specific definitions is included in the kit (LDDEF.H). This file will be included in VMS from version V8.2-1 and up. The only function to control the driver is IO$_LD_CONTROL which is defined in LDDEF.H. A sub-function must be given as P6 of the QIO request.
1 – Connect
This function connects a file to a logical disk:
Method 1 (old):
Function: IO$_LD_CONTROL
P1 = address of SBK block (Attributes Statistics Block) returned
by XQP IO$_ACCESS!IO$M_ACCESS function used to open the file
to connect.
P2 = logical disk size. If 0, the allocated size will be used
P3 = Number of tracks (optional)
P4 = Number of sectors (optional)
P5 = Number of cylinders (optional)
P6 = Subfunction: LDIO$K_CONNECT
Method 2 (new, preferred):
Function: IO$_LD_CONTROL
P1 = address of itemlist describing the connection
P6 = Subfunction: LDIO$K_CONNECT | LDIO$M_ITEMLIST
The P6 argument may also contain the following sub-flags:
LDIO$M_LOCK Will lock the container file
LDIO$M_NOFE Will set the NOFE bit to prevent handling
forced errors.
The itemlist consist of entries like this:
BUFLEN (word) - Length of buffer
ITEM (word) - Item description:
LDITM$K_CHANNEL
LDITM$K_EXTENDSIZE
LDITM$K_EXTENDLIMIT
LDITM$K_DEVICENAME
LDITM$K_FILEID
LDITM$K_STARTLBN
LDITM$K_ENDLBN
LDITM$K_FLAGS
LDITM$K_TRACKS
LDITM$K_CYLINDERS
LDITM$K_SECTORS
LDITM$K_MAXBLOCKS
ADDR (longword) - Pointer to buffer
RLENGTH (longword) - Returned data length
The following flags are for tape use only:
LDIO$M_INIT Will init the tape metadata
LDIO$M_NOLOAD Will create the unit without an attached containerfile
LDIO$M_LOADONLY Will load a containerfile to an existing unit
LDIO$M_EXTEND Extend containerfile on demand
This function connects a complete physical disk to a logical disk:
Function: IO$_LD_CONTROL
P1 = descriptor of buffer which contains device name of
physical device
P6 = Subfunction: LDIO$K_CONNECT | LDIO$M_REPLACE
This function connects a partial physical disk to a logical disk:
Function: IO$_LD_CONTROL
P1 = descriptor of buffer which contains device name of
physical device
P2 = Starting LBN (logical block number)
P3 = Ending LBN
P4 = Number of LBN's
P6 = Subfunction: LDIO$K_CONNECT | LDIO$M_LBN
Either P3 or P4 must be specified.
IOSB word 0 = status
Errors returned:
SS$_DEVACTIVE Device already connected
SS$_FORMAT FCB specified in SBK is invalid or file not opened
SS$_ACCVIO One of the parameters cannot be read/written
SS$_IVDEVNAM Attempt to connect to devicetype other than a disk
SS$_FILNOTCNTG Logical disk file not contiguous
SS$_DATAOVERUN Filename of file to connect too long
SS$_FILALRACC File already in use (may be on other cluster nodes)
SS$_ILLKLKNUM Disk size specified in P2 past end of file
SS$_IVADDR Disk bigger than 2097151 blocks
SS$_NORMAL Successful completion
SS$_BADPARAM Invalid geometry information specified
SS$_NOSUCHNODE Shared access was specified while no cluster code
is loaded
SS$_ACCONFLICT Shared access was specified while the device is
not cluster-wide visible
SS$_WRONGACP Container file is not on ODS-2 or ODS-5 disk
SS$_WRONGSTATE Container file is not opened without caching (V8.2 and up)
SS$_BADFILESIZE Container file too small (needs at least 5000 blocks) (Only for tape)
The following errors are returned for LDIO$M_REPLACE or
LDIO$M_LBN only:
SS$_DEVFOREIGN Device foreign mounted
SS$_DEVMOUNT Device mounted
SS$_DEVALLOC Device already allocated
Other possible errors are errors returned by the lockmanager
and errors returned by IOC$SEARCH.
2 – Disconnect
This function disconnects a file or device from a logical disk: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_DISCONNECT IOSB word 0 = status The subfunctionmodifier LDIO$M_ABORT allows the file to be disconnected regardless of it's state. The following flag is for tape use only: LDIO$M_KEEP Will disconnect the container file but keep the unit available for reuse. LDIO$M_TRUNCATE Will truncate the container file to the last written block (valid only of the containerfile was connected with extend enabled). Errors returned: SS$_DEVFOREIGN Device mounted foreign SS$_DEVMOUNT Device mounted SS$_BADFILEHDR Bad logical disk file SS$_DEVASSIGN Device still active (reference count > 0) SS$_DEVINACT Device not connected SS$_FORMAT FCB specified in SBK is invalid SS$_ACCVIO SBK block cannot be read SS$_NORMAL Successful completion Other possible errors are errors returned by the lockmanager.
3 – Display status
This function retrieves the current status of a LDAn device:
Function: IO$_LD_CONTROL
Method 1 (old):
P1 = address of buffer which receives the device- or filename
currently connected
P2 = size of buffer which receives the device- or filename
P3 = address of 3 word buffer which receives the file-id of the
connected file
P4 = Address of buffer to receive start lbn (for lbn mapping)
P5 = Address of buffer to receive end lbn (for lbn mapping)
P6 = Subfunction: LDIO$K_GET_CONNECTION
Method 2 (new, preferred):
P1 = address of itemlist describing the connection
P6 = Subfunction: LDIO$K_GET_CONNECTION |LDIO$M_ITEMLIST
The itemlist consist of entries like this:
BUFLEN (word) - Length of buffer
ITEM (word) - Item description:
LDITM$K_EXTENDSIZE
LDITM$K_EXTENDLIMIT
LDITM$K_DEVICENAME
LDITM$K_FILEID
LDITM$K_STARTLBN
LDITM$K_ENDLBN
LDITM$K_FLAGS
ADDR (longword) - Pointer to buffer
RLENGTH (longword) - Returned data length
IOSB word 0 = status
word 1 = number of characters transferred
longword 1 = status flag bit 0 : 0 = disconnected
1 = connected
bit 1 : 0 = normal connection
1 = replaced drive
bit 2 : 0 = normal connection
1 = replaced to DECRAM disk
bit 3 : 0 = normal access
1 = write protected
bit 4 : 0 = local access
1 = shared access
bit 8 : 0 = normal timing
1 = accurate timing
bit 9 : 0 = normal trace
1 = FDT trace active
bit 10: 0 = normal connection
1 = LBN mapping used
The buffer specified in the P1 parameter is only valid when
the unit is connected (IOSB longword 1 bit 0 set).
If a buffersize of 0 is specified only the status is returned.
The itemlist consist of entries like this:
Errors returned:
SS$_ACCVIO Buffer can not be written
SS$_DEVINACT Device not connected
SS$_NORMAL Successful completion
4 – Disable protect
This function unprotects a drive: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_DISABLE_PROTECT IOSB word 0 = status Errors returned: SS$_NORMAL Successful completion
5 – Disable trace
This function disables tracing: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_DISABLE_TRACE IOSB word 0 = status Errors returned: SS$_NODATA Trace is not active SS$_NORMAL Successful completion
6 – Disable watch
This function disables watchpoints: Function: IO$_LD_CONTROL P1 = address of watchpt structures P2 = number of watchpt structures, if 0 all entries will be removed P6 = Subfunction: LDIO$K_DISABLE_WATCH The watchpt structure (if specified) must contain a matching lbn, action, function, flags and returncode. These can all be retrieved with the LDIO$K_GET_WATCH function. IOSB word 0 = status longword 1 = current number of watchpoints Errors returned: SS$_DATALOST No active watchpoints SS$_DATACHECK Specified entry not found SS$_NORMAL Successful completion
7 – Enable protect
This function write-protects a drive: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_ENABLE_PROTECT IOSB word 0 = status Errors returned: SS$_NORMAL Successful completion
8 – Enable trace
This function enables tracing: Function: IO$_LD_CONTROL P1 = number of trace buffer packets to allocate P6 = Subfunction: LDIO$K_ENABLE_TRACE IOSB word 0 = status To reset the tracebuffer the additional subfunctionmodifier LDIO$M_RESET can be specified. No new tracebuffer will be allocated when that is done. Requests for FDT tracing need to add the subfunctionmodifier LDIO$M_FDTTRACE. Requests for accurate timing tracing need to add the subfunctionmodifier LDIO$M_ACCURATE. Specifying LDIO$M_TRACE_ALL will enable tracing of requests going to the container file as well (tapes only). Errors returned: SS$_ACCVIO Parameter cannot be read SS$_BADPARAM Zero buffer size specified SS$_EXBYTLM Exceeded BYTLM quota for the process SS$_INSFMEM Not enough memory to allocate trace buffer SS$_TOOMUCHDATA Trace is already active SS$_NORMAL Successful completion
9 – Enable watch
This function enables watchpoints: Function: IO$_LD_CONTROL P1 = address of watchpt structures P2 = number of watchpt structures P6 = Subfunction: LDIO$K_ENABLE_WATCH The watchpt structure must contain a valid lbn, action, function, flags and returncode. IOSB word 0 = status longword 1 = current number of watchpoints Errors returned: SS$_ACCVIO Buffer can not be read SS$_NOPRIV Action needs ownership of device or CMKRNL SS$_NOCMKRNL CMKRNL privilege needed for CRASH action SS$_EXBYTLM Out of BYTLIM quota for watch buffers SS$_DEVREQERR FILE watchpoint must be on the LD device SS$_ILLBLKNUM Watchpoint past end of file or end of disk or VBN zero specified for file SS$_BADPARAM Zero buffer length specified or action out of range SS$_FORMAT FCB specified in SBK is invalid or file not opened with cathedral windows SS$_INSFMEM Not enough memory to allocate watchpoint buffer SS$_NORMAL Successful completion
10 – Get suspend list
This function retrieves the list of suspended watchpoints: Function: IO$_LD_CONTROL P1 = address of suspend_list structures P2 = size in bytes of suspend_list buffer P6 = Subfunction: LDIO$K_GET_SUSPEND_LIST This function reads the number of suspended watchpoints: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_GET_SUSPEND_LIST | LDIO$M_INQUIRE IOSB word 0 = status word 1 = number of bytes written longword 1 = current number of suspended watchpoints Errors returned: SS$_INSFMEM Not enough memory to allocate temporary buffer SS$_ACCVIO Buffer can not be written SS$_DATALOST No active watchpoints SS$_IVBUFLEN Output buffer too small SS$_NORMAL Successful completion
11 – Get version
This function retrieves the driver version. Function: IO$_LD_CONTROL P1 = address of a longword to get the driver version format (Currently 1) P2 = address of a quadword to receive the driver's linktime P6 = Subfunction: LDIO$K_GET_VERSION IOSB word 0 = status Errors returned: SS$_ACCVIO Buffer can not be written SS$_NORMAL Successful completion SS$_SYNCH Successful completion (MON version)
12 – Get metadata
This function retrieves the tape metadata. See LDSTRDEF.H in the source kit for the layout of the buffer (struct LDTPMD). Function: IO$_LD_CONTROL P1 = address of a data buffer to retrieve the metadata P2 = buffer length (should be 512 bytes) P6 = Subfunction: LDIO$K_GET_METADATA IOSB word 0 = status Errors returned: SS$_ACCVIO Buffer can not be written SS$_NODATA No metadata available SS$_BUFFEROVF Buffer too small SS$_NORMAL Successful completion
13 – Get watch
This function retrieves watchpoints: Function: IO$_LD_CONTROL P1 = address of watchpt structures P2 = size in bytes of watchpt buffer P6 = Subfunction: LDIO$K_GET_WATCH This function reads the number of watchpoints: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_GET_WATCH | LDIO$M_INQUIRE IOSB word 0 = status word 1 = number of bytes written longword 1 = current number of watchpoints Errors returned: SS$_INSFMEM Not enough memory to allocate temporary buffer SS$_ACCVIO Buffer can not be written SS$_DATALOST No active watchpoints SS$_IVBUFLEN Output buffer too small SS$_NORMAL Successful completion
14 – Load
This function loads a container file to an existing tapeunit. Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_LOAD For all other parameters see the description of the Connect driver function.
15 – Read tracebuffer
This function reads the tracebuffer size: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_GET_TRACE | LDIO$M_INQUIRE IOSB word 0 = status word 1 = 0 longword 1 = tracebuffer size (number of packets) If the iosb status is SS$_WASSET FDT tracing is active. This function reads the tracebuffer data: Function: IO$_LD_CONTROL P1 = address of buffer which receives trace info P2 = size of trace buffer in bytes P6 = Subfunction: LDIO$K_GET_TRACE IOSB word 0 = status word 1 = 0 longword 1 = number of packets transferred or the number of lost packets in case of SS$_DATAOVERRUN. If the return status was SS$_DATAOVERRUN the buffer contains the number of packets as returned by the LDIO$K_GET_TRACE | LDIO$M_INQUIRE function. To read the tracebuffer data and to reset the buffer after the data has been read the subfunctionmodifier LDIO$M_RESET can be specified. If LDIO$M_NOWAIT is omitted the I/O request will wait until new trace data is available. Errors returned: SS$_ACCVIO Buffer can not be written SS$_NODATA Trace is not active SS$_IVBUFLEN Buffer too small to contain all trace data SS$_DATAOVERRUN The tracebuffer has been overrun SS$_NORMAL Successful completion
16 – Reset tracebuffer
This function resets the tracebuffer: Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_RESET_TRACE IOSB word 0 = status Errors returned: SS$_NODATA Trace is not active SS$_NORMAL Successful completion
17 – Resume watch
This function resumes a suspended watchpoint: Function: IO$_LD_CONTROL P1 = address of suspend_list structures P2 = size in bytes of suspend_list buffer P6 = Subfunction: LDIO$K_RESUME_WATCH IOSB word 0 = status word 1 = number of bytes written Errors returned: SS$_INSFMEM Not enough memory to allocate temporary buffer SS$_ACCVIO Buffer can not be written SS$_DATALOST No active watchpoints SS$_DATACHECK Nothing resumed SS$_NORMAL Successful completion
18 – Set allocation class
This function enables presetting of the allocation class of the LD device. This may only be done when no devices are connected. Function: IO$_LD_CONTROL P1 = allocation class P6 = Subfunction: LDIO$K_SET_ALLOCLASS IOSB word 0 = status Errors returned: SS$_BADPARAM Allocation class > 255 specified SS$_UNSAFE There are still connected LD devices SS$_NORMAL Successful completion
19 – Set unitnumber
This function enables presetting of the next assigned unitnumber. Function: IO$_LD_CONTROL P1 = unitnumber to preset P6 = Subfunction: LDIO$K_SET_SEED IOSB word 0 = status Errors returned: SS$_BADPARAM Unitnumber less than 0 or greater than 9999 SS$_NORMAL Successful completion
20 – Unload
This function unloads a container file from a tapeunit. Function: IO$_LD_CONTROL P6 = Subfunction: LDIO$K_UNLOAD For all other parameters see the description of the Disconnect driver function.
21 – Other features
After modification of the driver it is possible to RELOAD it without rebooting the system, provided that the size of the UCB did not change. If the reloaded driver detects a different UCB size, the unit will be placed off-line and the system has to be rebooted. The reload is only possible on a VAX. If there is still a file or device connected to any LDAn device the driver cannot be reloaded. In that case all LDAn devices have to be disconnected first. If a tracebuffer is allocated before reloading, it will be deallocated. All trace data will be lost.