ATG_FT_PATCH, Utilities, ATG FTDRIVER patch kit

ATG FTDRIVER patch kit, release X01.05
Nick de Smith, 06-Jan-92

Comments etc.
Nick de Smith (ATG310::NICK)
NICK@NCDLAB.ULCC.AC.UK	PSI%234213300154::NICK

The ATG_FT patches allow programs using the DEC supplied pseudo-terminals
(FTAn:) to set the access port name string for the device, such that a $GETDVI
with DVI$_TT_ACCPORNAM can retrieve the name. This also means that a "SHOW
TERMINAL" command will also display the set name.

This code has been checked by DEC, but carries no warranty from them, or from
the author. However, it has been carefully field tested in both SMP and
uniprocessor environments up to VMS V5.5.


Changes in X01.05
1. You can no longer use DVI$_LOCKID to return the PID of the process that
called PTD$CREATE to generate the FTAn: device. The problem was that the
PCB$L_CPID field (which has the same address as PCB$L_LOCKID) is used by the VMS
UCB create/delete processing code to credit byte count quota back to the
creating process. Use of DVI$_LOCKID now returns the MPID (which is the IPID of
the master process in the job tree), rather than the EPID of the creating
process.  To convert an IPID to an EPID (the one used by SHOW SYSTEM etc.) use
the ATG_CONVERT_IPID_TO_EPID.MAR routine in this kit.

Note that this will not generally be a problem as the master process in a job
tree will almost certainly be the creator of the FT device, unless you are
running in a sub-process.

2. A couple of potential problems were revealed during the code review by DEC
(thanks). These related to possible page faults at elevated IPLs, and have now
been removed.


Installation
------------

Execute (in order):
	$ @ATG_FT_BUILD.COM
	$ @ATG_FT_INSTALL.COM
	$ @ATG_FT_START.COM
You will need CMKRNL and BYPASS (or similar) to execute ATG_FT_START.COM.

Usage
-----

Once you have built, installed and started the ATG FTDRIVER patches, you may
use:
	unsigned long l_status;
	unsigned short w_chan;		/* Returned from PDT$CREATE() */
	$DESCRIPTOR( x_accpornam, "an access port name" );
	$DESCRIPTOR( x_devnam, "FTA34:" );

	l_status = ATG_FT_SET_ACCPORNAM( w_chan, [ &x_devnam ], &x_accpornam );

	Returned status:
		SS$_NORMAL	Success
		SS$_IVCHAN	Illegal channel (not from PDT$CREATE)
		SS$_IVDEVNAM	"devnam" was not an FT device
		SS$_NOSUCHDEV	"devnam" was not found
		SS$_DEVOFFLINE	Device offline
		SS$_NOPRIV	No privilege (wrong access mode)
		SS$_ACCVIO	Invalid string descriptor specified
		SS$_UNSUPPORTED	ATG_FT_START has not been run yet
		SS$_BADPARAM	Specified string > 63 characters long
				or both "chan" and "devnam" are 0.

;	The routine supplied is:
;
;	sts.wl = ATG_FT_SET_ACCPORNAM( chan.rw.v, [devnam.rx.d], text.rx.d )
;
;	sts	longword, write, by value
;		Returned system status
;
;	chan	word, read, by value
;		Channel number of FT device (from PTD$CREATE)
;		If this word is 0, the "devnam" argument is used to locate the
;		device
;
;	devnam	string, read, by descriptor, optional
;		Device name of FT device to modify. Used only if "chan" is 0.
;		You must have LOGICAL access to the device to specify it by name
;
;	text	string, read, by descriptor
;		Access port name string to set. Must be <= 63 characters.
;		

To call ATG_FT_SET_ACCPORNAM, you have to link your program thus:

	$ LINK .....,SYS$INPUT/Option
	...
	SYS$SHARE:ATG_FT_USS.EXE /Share
	...
	$!


Source files
------------
The following files are in this directory:

ATG_FT_BUILD.COM
Builds ATG_FT_PATCH.EXE, ATG_FT_USS.EXE and ATG_FT_START.EXE from their
appropriate .MAR files.

ATG_FT_INSTALL.COM
Installs ATG_FT_PATCH.EXE in SYS$COMMON:[SYS$LDR], ATG_FT_USS.EXE in
SYS$COMMON:[SYSLIB] and ATG_FT_START.* in SYS$COMMON:[SYSMGR].

ATG_FT_START.COM
File used to start up the ATG FTDRIVER patches. Should normally be called from
within SYS$STARTUP:SYSTARTUP_V5.COM, but may be executed any time after
ATG_FT_INSTALL.COM. CMKRNL and SYSNAM (or SYSPRV or BYPASS) privileges are
needed.

ATG_FT_PATCH.MAR
Source for ATG_FT_PATCH.EXE (used by ATG_FT_BUILD.COM)

ATG_FT_USS.MAR
Source for ATG_FT_USS.EXE (used by ATG_FT_BUILD.COM)

ATG_FT_START.MAR, LOADER_ERRORS.MSG
Source for ATG_FT_START.EXE (used by ATG_FT_BUILD.COM)
Note that LOADER_ERRORS.MSG is the file of error messsages generated by the
LDR$xxxx routines. It is needed here to enable ATG_FT_START.EXE to print
meaningful messages if there are any problems. Copyright of LOADER_ERRORS.MSG is
with DEC.

[end]