From:	CRDGW2::CRDGW2::MRGATE::"SMTP::CRVAX.SRI.COM::RELAY-INFO-VAX"  5-JAN-1991 03:36:47.26
To:	MRGATE::"ARISIA::EVERHART"
CC:	
Subj:	Re: Help using LIB$SET_LOGICL to create search list

Received:  by crdgw1.ge.com (5.57/GE 1.80)
	 id AA05667; Sat, 5 Jan 91 03:12:09 EST
Received: From SOL1.GPS.CALTECH.EDU by CRVAX.SRI.COM with TCP; Fri,  4 JAN 91 21:17:33 PST
Date: Fri, 04 Jan 1991 21:09:31 PST
From: carl@SOL1.GPS.CALTECH.EDU (Carl J Lydick)
To: siegel@stsci.edu
Cc: info-vax@sri.com
Message-Id: <00942390.e1490960.15615@SOL1.GPS.CALTECH.EDU>
Subject: Re: Help using LIB$SET_LOGICL to create search list

 > I've used LIB$SET_LOGICAL plenty to create a logical name with a single
 > translation with no problems.  Now I want to create a logical name with
 > multiple equivalence values (eg. a search list), and I'm not getting
 > very good results at all.  Given the test program (attached below), I am
 > trying to create a supervisor mode, process logical name SUITS which
 > will translate to the search list HEARTS,DIAMONDS,SPADES,CLUBS.  When I
 > run the program the first time, it signals SS$_NORMAL, but when I do a
 > SHOW LOGICAL SUITS, I get a %SHOW-S-NOTRAN error.  If I run the program
 > again, it signals SS$_SUPERSEDE.  Again SHOW LOGICAL SUITS gives a 'NOTRAN'
 > error.  However, I can successfully deassign the logical without getting
 > an error.  In addition, using another test program which uses $TRNLNM,
 > I find the logical does exist but has a maximum index count of -1 (meaning
 > the logical has no translations).  What is going on here????????  (The
 > documentation on the use of the item-list parameter to LIB$SET_LOGICAL
 > is sorely lacking in details; it says to use an Item_List_2 data structure
 > for the equivalence name strings, but does not give any details of how
 > to fill in the item-code field of the each element of the list).

 > I have not tried using $CRELNM to do the work because the program that
 > this is destined for will not have benefit of process/installed privs to
 > run and must be able to create supervisor mode logicals.

You're right, the documentation is really off the wall.  However, I recalled
that $CRELNM also accepts an item list, and it is well-documented.  So I tried
setting up the item list for LIB$SET_LOGICAL the same way I would for $CRELNM,
and it worked.  Assuming that this is not a special case that works only
because of some strangeness of the data, the information needed to overcome the
missing/erroneous documentation is:
	1)  What you want is an array of ITEM_LIST_3 data structures,
	    terminated, as usual, by a zero longword where the buffer length
	    and item code of the next item would normally go;
	2)  The item code should be one of those acceptable to $CRELNM.  The
	    two interesting ones are LNM$_STRING which allows you specify an
	    equivalence name, and LNM$_ATTRIBUTES, which lets you specify the
	    attributes to be applied to equivalence names specified in
	    subsequent LNM$_STRING items; 
The following modified version of your program works properly.  Hope this helps.

<-= cut here =-> <-= cut here =-> <-= cut here =-> <-= cut here =->

	PROGRAM		EXAMPLE
C
	IMPLICIT	NONE
	INCLUDE		'($LNMDEF)'
C
	STRUCTURE	/ITEM_LIST_3/
		UNION
			MAP
				INTEGER*2   LENGTH          /0/
				INTEGER*2   CODE            /0/
				INTEGER*4   ADDRESS         /0/
				INTEGER*4   RESULT          /0/
			END MAP
			MAP
				INTEGER*4   END_OF_LIST(3)  /0, 0, 0/
			END MAP
		END UNION
	END STRUCTURE
C
	INTEGER*4	STS, LIB$SET_LOGICAL
	RECORD		/ITEM_LIST_3/ ITMLST(5)
C
C---------------------------------------------------------------------------
C
	ITMLST(1).CODE			= LNM$_STRING
		ITMLST(1).LENGTH	= LEN('HEARTS')
		ITMLST(1).ADDRESS	= %LOC('HEARTS')
		ITMLST(1).RESULT	= 0
	ITMLST(2).CODE			= LNM$_STRING
		ITMLST(2).LENGTH	= LEN('DIAMONDS')
		ITMLST(2).ADDRESS	= %LOC('DIAMONDS')
		ITMLST(2).RESULT	= 0
	ITMLST(3).CODE			= LNM$_STRING
		ITMLST(3).LENGTH	= LEN('SPADES')
		ITMLST(3).ADDRESS	= %LOC('SPADES')
		ITMLST(3).RESULT	= 0
	ITMLST(4).CODE			= LNM$_STRING
		ITMLST(4).LENGTH	= LEN('CLUBS')
		ITMLST(4).ADDRESS	= %LOC('CLUBS')
		ITMLST(4).RESULT	= 0
C
	STS = LIB$SET_LOGICAL('SUITS', , , , ITMLST)
	CALL LIB$SIGNAL(%VAL(STS))
C
	CALL EXIT
	END

