LD$HELP.HLB  —  LD  Driver functions
 	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.
Close Help