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

[Simon Clubley]

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