[Info-vax] Questions about sys$cli()

[John Reagan]

On Saturday, June 29, 2019 at 6:42:51 PM UTC-4, Simon Clubley wrote:
> I've been looking at sys$cli() because I was interested in seeing
> how DCL interacts with the rest of the system at this level.
> Once I understood what was going on, much of it was as expected,
> but I do have some questions.
> 
> 1) There's a structure (struct clidef) near the start of the CLIDEF
> C header which I have not been able to find out how it is used.
> It contains (for example) a variable called cli$a_progxfer which is
> described as the Program Transfer Vector Address and a variable called
> cli$a_utilserv which is described as the Address of the CLI Utility
> Service.
> 
> Is this structure some artifact from an earlier version of VMS and is
> now obsolete, or does it map to a DCL memory area which I have not
> found yet ?
> 
> 2) This one is a strange one. When calling CLI$K_DEFGLOBAL to define
> a global symbol, if I use normal string descriptors which have been
> setup with $DESCRIPTOR() then the call fails.
> 
> If I make the descriptors invalid by clearing out the dsc$b_dtype and
> dsc$b_class fields, then the call works! !!!????!!!!!
> 
> The following is a complete and compilable example which shows the
> problem on HPE Alpha VMS 8.4.
> 
> WARNING: if you try this program on other VMS versions or other
> architectures and get compilation errors, check to see if the
> clidef$$_fill_8 field is still part of the clidef2 struct on that
> VMS version.
> 
> #include <stdio.h>
> #include <string.h>
> #include <clidef>
> #include <cliservdef>
> #include <descrip>
> 
> unsigned long int sys$cli(void *);
> 
> struct clidef1 *clihdr;
> struct clidef2 setsym;
> 
> $DESCRIPTOR(sym_name, "ABCD");
> $DESCRIPTOR(sym_value, "ABCD_value");
> 
> int main(int argc, char *argv[])
> 	{
> 	unsigned long int ret_stat;
> 
> 	memset(&setsym, 0, sizeof(setsym));
> /*
>  * Overlaying clidef1 is yucky (to put it mildly :-() but the layout of the
>  * HPE supplied CLIDEF C header doesn't exactly give you any clean options.
>  */
> 	clihdr = (struct clidef1 *) &setsym.clidef$$_fill_8[0];
> 	clihdr->cli$b_rqtype = CLI$K_CLISERV;
> 	clihdr->cli$w_servcod = CLI$K_DEFGLOBAL;
> 	clihdr->cli$b_rqstat = 0;
> 
> /*
>  * Uncomment the following 4 descriptor assignments to make this program work.
>  *
>  * Unless the following 4 descriptor fields are reset to zero, CLI$K_DEFGLOBAL
>  * fails with a status of 229688 on HPE Alpha V8.4. The reason for this is
>  * unknown.
>  */
> //	sym_name.dsc$b_dtype = 0;
> //	sym_name.dsc$b_class = 0;
> 
> //	sym_value.dsc$b_dtype = 0;
> //	sym_value.dsc$b_class = 0;
> 
> 	memcpy(&setsym.cli$q_namdesc[0], &sym_name, 8);
> 	memcpy(&setsym.cli$q_valdesc[0], &sym_value, 8);
> 
> 	ret_stat = sys$cli(&setsym);
> 	printf("ret_stat = %lu\n", ret_stat);
> 
> 	return 1;
> 	}
> 
> This program was compiled with:
> 
> $ cc/warn=warning=all descr_problem.c
> $ link descr_problem
> 
> When the 4 indicated lines are commented out, this is what happens:
> 
> $ del/sym/glo abcd
> %DCL-W-UNDSYM, undefined symbol - check validity and spelling
> $ r descr_problem
> ret_stat = 229688
> $ sh sym/global abcd
> %DCL-W-UNDSYM, undefined symbol - check validity and spelling
> $ abcd == "dfdfdfdfdfdfdfdfdf"
> $ sh sym/global abcd
>   ABCD == "dfdfdfdfdfdfdfdfdf"
> $ r descr_problem
> ret_stat = 229688
> $ sh sym/global abcd
> %DCL-W-UNDSYM, undefined symbol - check validity and spelling
> 
> As you can see, the program goes badly wrong, not only refusing
> to create a new global symbol, but actually gets as far as deleting
> an existing global symbol of the same name in the second test
> (but not replacing it with the new definition).
> 
> When the 4 indicated lines are uncommented, this is what happens:
> 
> $ del/sym/glo abcd
> %DCL-W-UNDSYM, undefined symbol - check validity and spelling
> $ r descr_problem
> ret_stat = 1
> $ sh sym/global abcd
>   ABCD == "ABCD_value"
> 
> As you can see, the program now works.
> 
> The status text is:
> 
> $ write sys$output f$message(229688)
> %CLI-W-SYMOVF, no room for symbol definitions - delete some symbols
> 
> Does anyone know why clearing dsc$b_dtype and dsc$b_class makes the
> program start working ?
> 
> 3) It looks like there are two distinct versions of the CLI$K_SPAWN API
> and the API version is selected by setting cli$b_version to 0 or 1.
> Some of the clidef5 fields appear to be ignored unless cli$b_version is
> set to 1.
> 
> Are there any other functionality differences in how the two versions of
> CLI$K_SPAWN work internally ? Was the API version changed as the result
> of some requests to add new functionality which could not be added without
> breaking the API ?
> 
> Thanks,
> 
> Simon.
> 
> -- 
> Simon Clubley, clubley at remove_me.eisner.decus.org-Earth.UFP
> Microsoft: Bringing you 1980s technology to a 21st century world

It isn't a normal descriptor.  

SYS$CLI "normally" has more than one argument. [There is nothing "normal" about SYS$CLI in my opinion.]

And depending on your context, SYS$CLI may end up in different code with possibly different meaning of the arguments.  

These are some of the main reasons (excuses?) used over the years for not documenting it and/or not supporting a full user-written CLI.