Conference turris::languages

With that many, I would indeed use an item list, especially if many of those
are optional.

You'd have to check on COBOL (a language I knew once on an IBM long ago and
far away and forgot like a bad dream :-) ) and BASIC, but I've used most of 
the others recently.

A typical item list entry has:
1) a space for the buffer length, 
2) a space for an item code of some sort,
3) a space for the buffer address, and 
4) a space for the address into which to place the actual length used.  
   (Null for "in" items)

The only things which could be potentially troublesome for item lists (besides
learning how to set one up) are:
1)  getting the address of (in your case) a string
2)  getting the address of a longword
3)  forming an array of records.
4)  placing a zero constant in a field intended to hold an address

All of the technical languages have at least one way of doing this.  Some are
more implementation-specific than others.  I believe BASIC doesn't have much
trouble with this either.  COBOL doesn't really shine at this sort of low-level
stuff, but the VAX implementation might just possibly support this.

DEC already has too many item-list formats.  Be sure to use one that already
exists, preferably the one used by $GETxxx and $SNDJBC, since that will appear
in everyone's renditions of STARLET.

							Ralph

    The 1988 Software Engineering Manual (Appendix G, page 5) list the
    following document: 
    
    	Siva::Sys$Public:Callable.Mem
    
    as "Making Layered Products Callable".  It's a product of the SARA
    Technical Office.
                                               
    Hope that helps,
    
    douglas

	Well I can't access SIVA::SYS$PUBLIC:CALLABLE.MEM since
	SYS$PUBLIC is not world readable. So much for that idea
	for now.

	I have considered using a "standard" item list, or even an
	array of pointers to descriptors.  Any comments on whether
	you can create an array of pointers to descriptors from the
	various VAX/VMS languages.

	Is anyone familiar with the CDD/PLUS Callable Routines?
	They took an interesting approach to the data block/item list
	problem.  Rather than passing a reference to an item list,
	they pass descriptors as follows:

		VMS usage:	unstructured
		type:		text
		access:		read only
		mechanism	by descriptor (static or dynamic)

	Some descriptors point to complicated data structures,
	with optional fields preceded by one byte item codes, and
	variable length strings preceded by a length word.  The PASCAL
	examples they provide to manipulate these strings are messy,
	but seem workable.  It really does seem like CDD took an item
	list, and passed it as a string.  Any comments on this approach?
	I assume you can access the CDD routines from COBOL etc.


					David

>	I have considered using a "standard" item list, or even an
>	array of pointers to descriptors.  Any comments on whether
>	you can create an array of pointers to descriptors from the
>	various VAX/VMS languages.

  That's not too hard in COBOL.  One of the DECWindows DRM routines
  takes such a thing.
  
  FWIW, everything we hear from CDD users says that it is a royal pain to use
  CDD/Plus's new callable interface from COBOL.

  Item lists are not that hard in VAX COBOL, and they are a known quantity
  in the field.

  Craig Neth
  VAX COBOL

  

    Another possibility is to use multiple procedure calls, especially
    if the typical user is only interested in one or two of those input
    and output descriptors.  You could have something along the lines
    of
    
    	CREATE_DESCRIPTOR_ARRAY(my_array);
    	SET_COUNTRY_STRING(my_array, "Transylvania");
    	SET_PLANET_STRING(my_array, "Kling");
    
    or

    	CREATE_DESCRIPTOR_ARRAY(my_array);
    	SET_STRING_BY_KEYWORD(my_array, fac$k_country, "Transylvania");
    	SET_STRING_BY_KEYWORD(my_array, fac$k_planet, "Kling");

    This would be extremely easy to use, though it has the expense of
    more procedure calls.
    
    Another possibility, given that your arguments arre all strings,
    might be to use an array descriptor or varying string array descriptor.
    Both of these are documented in the calling standard, but I don't
    know which languages, if any, provide language support for them.
    
       Gary

The general feedback from users is that item lists are fairly convenient
when programming in a medium level languages (BLISS and C) but they are
very awkward in high-level languages (Ada, Basic, COBOL, FORTRAN, Pascal, etc.).
Also, descriptor parameters are very convenient in high level languages but
there is no high level support for using descriptors in data structures
outside of parameter lists.

The suggested interface in .5 would probably be easier to use by the
naive high level language programmer than an interface that required
construction of item lists and/or descriptors outside of parameter lists.

    I'd like to add my support for the multiple-entry approach.  This
    style of interface is a lot less intimidating than the single
    routine/many parameters approach and, therefore, a lot more likely
    to get used.
    
    I'm a moderately experienced programmer (20+ years), but there are
    a few system services that I simply haven't the gumption to decipher.
    I mean, every time I try to use $GETQUI, I end up by deciding the
    application REALLY doesn't need that piece of functionality.

    Having once written COBOL, I would suggest that although things like
    item lists may not be TOO hard in COBOL, they are probably well above
    the level of the average commercial COBOL programmer. If "average
    commercial COBOL programmer" is a description of a significant segment
    of your potential user community, you had best keep the interface as
    simple as possible.
    
    -dave 
    

    On the other hand, lots of entry points can be intimidating, also.
    One of our selling points in DECforms is that we have reduced the large
    number of entry points provided by the older forms products to only
    six.  We use item lists only for things that the "ordinary programmer"
    are not likely to want to specify, so the "ordinary programmer" doesn't
    have to deal with item lists.
    
    I have used the CDD/Plus callable interface from Bliss, and I agree
    with the previous respondents that it is not easy to use.  Even though
    I am also a moderately experienced programmer (since 1964), and even
    though I got a lot of help from the CDD/Plus development group, and
    even though CDD/Plus provides very good error messages when you feed it
    a malformed buffer, and even though CDD/Plus has some good debugging
    tools, I still found it daunting.
    
    I suspect there is no good, general purpose, way to define a complex
    interface---you've got to design each one for the functions it will
    be providing, and with the intended audience in mind.  In DECforms we
    provide just a few entry points: Enable, Send, Receive, Transceive,
    Disable and Cancel.  However, this is just the interface to a whole
    programming language, that lets you express very complex operator
    interactions in the process of creating or modifying a record.  The
    trick is to define a simple interface to the application program,
    with a separately-specified complex operation "behind" the interface.
    Obviously, this technique won't work in all cases.
        John Sauter

        Thanks for all the feed back.  I am leaning towards a compromise
        approach that will allow better performance when calling from
        a medium or medium-high level languange, but will not exclude
        languages that do not support data blocks.

        While people are familiar with item lists, the item code field is
        irrelevant, since I am always passing or returning strings. 

	An array of pointers to descriptors is probably easier to use
	from most languages (although it would be nice to avoid the
	extra level of indirection). The supported descriptor classes will
	be fixed-length (DSC$K_CLASS_S), dynamic (DSC$K_CLASS_D), or
	varying string (DSC$K_CLASS_VS).  That should cover all the
	VAX/VMS languages.

	The user program will have to allocate storage for the array and
	the descriptors.  For languages that have trouble manipulating
	an array of pointers to descriptors, I will supply utility routines
	to insert or remove descriptor addresses.

	Another issue that needs to be resolved is how to communicate
	the total number of descriptors in the array, and the number
	being passed as input or output arguments in a single call.
	Obviously this could be done with two additional arguments,
	but I would rather include the counts as part of the data block.
	For example:

		+-------------------------------+
		|	Total number (N)	|
		+-------------------------------+
		| Current input/output count	|
		+-------------------------------+
		| Pointer to 1st descriptor     |
		+-------------------------------+
		| Pointer to 2nd descriptor     |
		+-------------------------------+
		                .
		                .
		                .
		+-------------------------------+
		| Pointer to Nth descriptor     |
		+-------------------------------+

	The utility routines can be used to initialize and modify
	the count fields.  Medium level languages such as BLISS and
	C, or high level languages such as PASCAL should not have
	any trouble with this data block.  Any comments on BASIC,
	FORTRAN, or COBOL?

					David

    It's been a long time, but I am pretty sure that VAX BASIC can have an
    array of descriptors, using a DSC$K_CLASS_A descriptor, with a
    DSC$K_DTYPE_DSC data type.  The descriptors pointed to are usually
    (possibly always) DSC$K_CLASS_D.  Passing an array by descriptor
    automatically handles the number of strings.
        John Sauter 

>< Note 229.3 by RUBELA::SCHWARTZ "VAX DSM Engineering" >
>                       -< Item lists by any other name >-
>
>
>	Well I can't access SIVA::SYS$PUBLIC:CALLABLE.MEM since
>	SYS$PUBLIC is not world readable. So much for that idea
>
    It's a bit late, but in case you still would like to receive this
    document, please contact the author, Mike TOHOKU::Taylor.  We are
    no longer archiving it on SIVA.

	The MUMPS ANSI standard has no explicit data typing.
	Variables can be treated as strings, numbers, or
	boolean depending on the context.  This allows for a
	great deal of flexibility in the MUMPS language.
	VAX DSM handles all implicit data type conversion.

	The VAX DSM callable interface will support input parameters
	in string descriptors (fixed, dynamic, and variable string)
	and signed longwords, but I can't decide how to handle floating
	point numbers.  Can anyone tell me what the most commonly
	used floating point data types are?  My gut feeling is supporting
	D_floating and F_floating will be sufficient.  For unsupported
	types, the calling routine can always convert from floating
	to string before calling VAX DSM.

	Also, does anyone have a recommendation for floating-to-string,
	and string-to-floating conversion routines that can be accessed
	from any high level language (LIB$, MTH$, OTS$, etc.) ?
	
		Thanks,

		David

    RE: .9
    
    	VAX Pascal can not create arrays of descriptors or pointers
    	to descriptors; it can only create descriptors of data objects
    	being passed to a procedure.  As described in .9, they
    	would have to be built by hand.
    
    RE: .12
    
    	Why only handle fixed, dynamic and varying string descriptors?
    	Call LIB$ANALYZE_SDESC.
    
    /steve

    RE .13

	After entering .9 I held a design review, and came up with a
	somewhat more flexible approach.  All calls to the VAX DSM
	database routines will pass "data blocks".  The structure of
	the data blocks will not be documented to the outside world.
	VAX DSM will provide utility routines to allocate, intialize,
	deallocate, insert arguments, and extract arguments from the
	data blocks.

	There will be two types of insert and extract routines.  One
	will accept a single argument at a time, and the other will
	accept an item list containing 1 to 40 arguments. This approach
	solves the following problems:

		- large number of input/output arguments
		- variable number of input/output arguments
		- support for languages that have difficulty
		  manipulating item lists
		- simple interface for languages that can easily
		  manipulate item lists

	As an added benefit, the internal structure of the data blocks
	will be in the format expected by the VAX DSM database routines.
	This saves an argument conversion/copy step on each database call.

	David

	Well its been a couple months, but I have completed the
	first pass at implementing the VAX DSM Callable Interface.
	The current implementation only allows data values to be
	input and output as strings.  I have had a request from an
	internal beta test site to accept integer and floating
	point as well.  They currently convert the numbers to string
	before calling VAX DSM, and must convert the output strings
	to numbers.

	I have considered extending my current routines to accept
	an additional argument which is the data type (string, integer
	float_d, float_f) of the input or output argument.  However,
	I am afraid the strongly typed languages don't allow this.
	The alternative is to create a separate set of routines for
	each data type I want to support.

	For example, in PASCAL I currently use the following
	external declaration:

	FUNCTION dsm$sdb_insert		{ string }
	    (%REF position : INTEGER;
	     %DESCR subscript : VARYING [124] OF CHAR;
	     %REF sdb : sdb_type) : cond_value;
	    EXTERNAL;

	In order to accept integer, float_f, and float_d I need
	to create 3 additional routines:

	FUNCTION dsm$sdb_insert_l	{ integer }
	    (%REF position : INTEGER;
	     %REF subscript : INTEGER;
	     %REF sdb : sdb_type) : cond_value;
	    EXTERNAL;


	FUNCTION dsm$sdb_insert_f	{ float_f }
	    (%REF position : INTEGER;
	     %REF subscript : SINGLE;
	     %REF sdb : sdb_type) : cond_value;
	    EXTERNAL;


	FUNCTION dsm$sdb_insert_d	{ float_d }
	    (%REF position : INTEGER;
	     %REF subscript : DOUBLE;
	     %REF sdb : sdb_type) : cond_value;
	    EXTERNAL;


	Is it possible provide this functionalily with a single
	entry point?  Something like:

	FUNCTION dsm$sdb_insert
	    (%REF position : INTEGER;
	     %REF data_type : INTEGER;	{ specifies the VMS data type }
	     %REF subscript : ???;
	     %REF sdb : sdb_type) : cond_value;
	    EXTERNAL;

	I have only used PASCAL as an example. The same problem
	exists for COBOL, BASIC, FORTRAN, C, ADA, PL/1 etc. (To their
	credit, BLISS and MACRO don't care!)

	There are currently 5 routines which pass strings.  If I need a
	separate entry point for the additional VMS data types, it will
	increase the number of routines to 20.  I realize you can
	pass integers and floating point numbers by descriptor, but
	this seems like a real hack!

	Any ideas or suggestions?

	Thanks,

	David

    In the situation you are in, passing integers and floating values by
    descriptor seems like a fine solution.
        John Sauter

I can't think of something less natural than programming with item lists.
Perhaps it's OK from Macro or BLISS, but who cares about languages from the
dark ages when the computers where born? Try do make a more object oriented
approach with procedures and normal parameters!

Olav