Does anybody have the callable BACKUP example in compilable format?

Trying to select and copy it from the PDF manual gives me garbage.

FWIW, that's the ugliest bit of VMS documentation I have read in a
very long while.

--
VAXman- A Bored Certified VMS Kernel Mode Hacker VAXman(at)TMESIS(dot)ORG

I speak to machines with the voice of humanity.

In article <00B6577C.58FA82EB@SendSpamHere.ORG>, VAXman- @SendSpamHere.ORG writes:
>Does anybody have the callable BACKUP example in compilable format?
>
>Trying to select and copy it from the PDF manual gives me garbage.
>
>FWIW, that's the ugliest bit of VMS documentation I have read in a
>very long while.

NEVERMIND. I wrote it in Macro. ;)

--
VAXman- A Bored Certified VMS Kernel Mode Hacker VAXman(at)TMESIS(dot)ORG

I speak to machines with the voice of humanity.

On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
> Does anybody have the callable BACKUP example in compilable format?
>
> Trying to select and copy it from the PDF manual gives me garbage.
>
> FWIW, that's the ugliest bit of VMS documentation I have read in a
> very long while.

I rewrote the example in the manual and ended up with:

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <descrip.h>

#include "sys$examples:bapidef.h"

typedef struct _buf_arg
{ bck_opt_struct_dsc arg1;
bck_opt_struct_dsc arg2;
bck_opt_struct_flag arg3;
bck_opt_struct_flag arg4;
bck_opt_struct_flag arg5;
} buf_arg;

int backup$start(buf_arg *mybufarg);

int main()
{ buf_arg mybufarg;;
int status;
$DESCRIPTOR(input_dsc, "[.ratfor...]");
$DESCRIPTOR(output_dsc, "ratfor.bck");
mybufarg.arg1.opt_dsc_type = BCK_OPT_K_INPUT;
memcpy(&mybufarg.arg1.opt_dsc, &input_dsc, 8);
mybufarg.arg2.opt_dsc_type = BCK_OPT_K_OUTPUT;
memcpy(&mybufarg.arg2.opt_dsc, &output_dsc, 8);
mybufarg.arg3.option_type = BCK_OPT_K_SAVE_SET_OUT;
mybufarg.arg3.opt_flag_value = TRUE;
mybufarg.arg4.option_type = BCK_OPT_K_OPERATION_TYPE;
mybufarg.arg4.opt_flag_value = BCK_OP_K_SAVE ;
mybufarg.arg5.option_type = BCK_OPT_K_END_OPT;
mybufarg.arg5.opt_flag_value = FALSE;
status = backup$start(&mybufarg);
exit(status);
}

BACKUP/LIST look OK on the result.

Arne

On 08/07/2021 18:49, Arne Vajhøj wrote:
> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>> Does anybody have the callable BACKUP example in compilable format?
>>
>> Trying to select and copy it from the PDF manual gives me garbage.
>>
>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>> very long while.
>
> I rewrote the example in the manual and ended up with:
>
> #include <stdio.h>
> #include <string.h>
> #include <stdlib.h>
> #include <descrip.h>
>
> #include "sys$examples:bapidef.h"
>
> typedef struct _buf_arg
> {
>     bck_opt_struct_dsc arg1;
>     bck_opt_struct_dsc arg2;
>     bck_opt_struct_flag arg3;
>     bck_opt_struct_flag arg4;
>     bck_opt_struct_flag arg5;
> } buf_arg;
>
> int backup$start(buf_arg *mybufarg);
>
> int main()
> {
>     buf_arg mybufarg;;
>     int status;
>     $DESCRIPTOR(input_dsc, "[.ratfor...]");
>     $DESCRIPTOR(output_dsc, "ratfor.bck");
>     mybufarg.arg1.opt_dsc_type = BCK_OPT_K_INPUT;
>     memcpy(&mybufarg.arg1.opt_dsc, &input_dsc, 8);
>     mybufarg.arg2.opt_dsc_type = BCK_OPT_K_OUTPUT;
>     memcpy(&mybufarg.arg2.opt_dsc, &output_dsc, 8);
>     mybufarg.arg3.option_type = BCK_OPT_K_SAVE_SET_OUT;
>     mybufarg.arg3.opt_flag_value = TRUE;
>     mybufarg.arg4.option_type = BCK_OPT_K_OPERATION_TYPE;
>     mybufarg.arg4.opt_flag_value = BCK_OP_K_SAVE ;
>     mybufarg.arg5.option_type = BCK_OPT_K_END_OPT;
>     mybufarg.arg5.opt_flag_value = FALSE;
>     status = backup$start(&mybufarg);
>     exit(status);
> }
>
> BACKUP/LIST look OK on the result.
>
> Arne
>
Always beware of copying/pasting from Word or PDF - it usually does
strange things - especially with quotes!

Chris

--
Chris

On 7/8/2021 5:42 PM, Chris Townley wrote:
> On 08/07/2021 18:49, Arne Vajhøj wrote:
>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>> Does anybody have the callable BACKUP example in compilable format?
>>>
>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>
>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>> very long while.
>>
>> I rewrote the example in the manual and ended up with:

>> BACKUP/LIST look OK on the result.
>>
> Always beware of copying/pasting from Word or PDF - it usually does
> strange things - especially with quotes!

It was more than copy/paste problems.

The example in the manual declared a function:

unsigned int subtest(void *);

without using it.

It did:

static char input_str[] = "[.wrk]";
....
input_dsc.dsc$w_length = sizeof(input_str);

which I believe must be off by 1.

It did not declare return type of main and it made all variables
global instead of local in main, which is valid C but not very
good C.

Arne

On 08/07/2021 23:53, Arne Vajhøj wrote:
> On 7/8/2021 5:42 PM, Chris Townley wrote:
>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>
>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>
>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>> very long while.
>>>
>>> I rewrote the example in the manual and ended up with:
>
>>> BACKUP/LIST look OK on the result.
>>>
>> Always beware of copying/pasting from Word or PDF - it usually does
>> strange things - especially with quotes!
>
> It was more than copy/paste problems.
>
> The example in the manual declared a function:
>
> unsigned int subtest(void *);
>
> without using it.
>
> It did:
>
> static char input_str[] = "[.wrk]";
> ...
> input_dsc.dsc$w_length = sizeof(input_str);
>
> which I believe must be off by 1.
>
> It did not declare return type of main and it made all variables
> global instead of local in main, which is valid C but not very
> good C.
>
> Arne
>
>
Ouch!

Chris

--
Chris

On 7/8/2021 7:11 PM, Chris Townley wrote:
> On 08/07/2021 23:53, Arne Vajhøj wrote:
>> On 7/8/2021 5:42 PM, Chris Townley wrote:
>>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>>
>>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>>
>>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>>> very long while.
>>>>
>>>> I rewrote the example in the manual and ended up with:
>>
>>>> BACKUP/LIST look OK on the result.
>>>>
>>> Always beware of copying/pasting from Word or PDF - it usually does
>>> strange things - especially with quotes!
>>
>> It was more than copy/paste problems.
>>
>> The example in the manual declared a function:
>>
>> unsigned int subtest(void *);
>>
>> without using it.
>>
>> It did:
>>
>> static char input_str[] = "[.wrk]";
>> ...
>> input_dsc.dsc$w_length = sizeof(input_str);
>>
>> which I believe must be off by 1.
>>
>> It did not declare return type of main and it made all variables
>> global instead of local in main, which is valid C but not very
>> good C.
>>
>> Arne
>>
>>
> Ouch!
>
> Chris
>

"Cut-n-Paste" usually means the user didn't bother to understand the
example/source. That isn't a good idea at any time. The doc examples
are to help one understand, not to be blindly copied.

--
David Froble Tel: 724-529-0450
Dave Froble Enterprises, Inc. E-Mail: davef@tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA 15486

On 7/8/2021 8:48 PM, Dave Froble wrote:
> On 7/8/2021 7:11 PM, Chris Townley wrote:
>> On 08/07/2021 23:53, Arne Vajhøj wrote:
>>> On 7/8/2021 5:42 PM, Chris Townley wrote:
>>>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>>>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>>>
>>>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>>>
>>>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>>>> very long while.
>>>>>
>>>>> I rewrote the example in the manual and ended up with:
>>>
>>>>> BACKUP/LIST look OK on the result.
>>>>>
>>>> Always beware of copying/pasting from Word or PDF - it usually does
>>>> strange things - especially with quotes!
>>>
>>> It was more than copy/paste problems.
>>>
>>> The example in the manual declared a function:
>>>
>>> unsigned int subtest(void *);
>>>
>>> without using it.
>>>
>>> It did:
>>>
>>> static char input_str[] = "[.wrk]";
>>> ...
>>> input_dsc.dsc$w_length = sizeof(input_str);
>>>
>>> which I believe must be off by 1.
>>>
>>> It did not declare return type of main and it made all variables
>>> global instead of local in main, which is valid C but not very
>>> good C.
>>
>> Ouch!
>
> "Cut-n-Paste" usually means the user didn't bother to understand the
> example/source.  That isn't a good idea at any time.  The doc examples
> are to help one understand, not to be blindly copied.

It is fair enough and in some cases even beneficial to just show
code snippets instead of complete code.

And it is obviously the copy pasters mistake if he copy paste code
that does something else than what he need.

But whatever is chosen to be shown should be OK code for a
purpose.

If they had not shown the descriptor initialization then it would
have been OK. The example intend to show BACKUP$ routines not
use of descriptors in C.

But they chose to show the code. And then the code should be correct.

Arne

In article <sc86be$cvo$1@dont-email.me>, Dave Froble <davef@tsoft-inc.com> writes:
>On 7/8/2021 7:11 PM, Chris Townley wrote:
>> On 08/07/2021 23:53, Arne Vajhøj wrote:
>>> On 7/8/2021 5:42 PM, Chris Townley wrote:
>>>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>>>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>>>
>>>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>>>
>>>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>>>> very long while.
>>>>>
>>>>> I rewrote the example in the manual and ended up with:
>>>
>>>>> BACKUP/LIST look OK on the result.
>>>>>
>>>> Always beware of copying/pasting from Word or PDF - it usually does
>>>> strange things - especially with quotes!
>>>
>>> It was more than copy/paste problems.
>>>
>>> The example in the manual declared a function:
>>>
>>> unsigned int subtest(void *);
>>>
>>> without using it.
>>>
>>> It did:
>>>
>>> static char input_str[] = "[.wrk]";
>>> ...
>>> input_dsc.dsc$w_length = sizeof(input_str);
>>>
>>> which I believe must be off by 1.
>>>
>>> It did not declare return type of main and it made all variables
>>> global instead of local in main, which is valid C but not very
>>> good C.
>>>
>>> Arne
>>>
>>>
>> Ouch!
>>
>> Chris
>>
>
>"Cut-n-Paste" usually means the user didn't bother to understand the
>example/source. That isn't a good idea at any time. The doc examples
>are to help one understand, not to be blindly copied.

I wanted something quick to play with but copying it from Preview on my
Mac to TextEdit produced put unadulterated garbage. What I don't under-
stand is why the various macros (C-headers) were never added into the
system's libraries. They need to be included from SYS$EXAMPLES. If the
*include* files can be placed into SYS$EXAMPLES, why wasn't the example?
After perusing that awful BACKUP API documentation, I whipped together a
macro example. Far more readable too.

If you want to wish you had a migraine a augmented by a hangover from a
college toga party coupled with a raging case of herpes, take a gander
at that BACKUP API documentation.

--
VAXman- A Bored Certified VMS Kernel Mode Hacker VAXman(at)TMESIS(dot)ORG

I speak to machines with the voice of humanity.

In article <00B65888.594833A3@SendSpamHere.ORG>, VAXman- @SendSpamHere.ORG writes:
>In article <sc86be$cvo$1@dont-email.me>, Dave Froble <davef@tsoft-inc.com> writes:
>>On 7/8/2021 7:11 PM, Chris Townley wrote:
>>> On 08/07/2021 23:53, Arne Vajhøj wrote:
>>>> On 7/8/2021 5:42 PM, Chris Townley wrote:
>>>>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>>>>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>>>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>>>>
>>>>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>>>>
>>>>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>>>>> very long while.
>>>>>>
>>>>>> I rewrote the example in the manual and ended up with:
>>>>
>>>>>> BACKUP/LIST look OK on the result.
>>>>>>
>>>>> Always beware of copying/pasting from Word or PDF - it usually does
>>>>> strange things - especially with quotes!
>>>>
>>>> It was more than copy/paste problems.
>>>>
>>>> The example in the manual declared a function:
>>>>
>>>> unsigned int subtest(void *);
>>>>
>>>> without using it.
>>>>
>>>> It did:
>>>>
>>>> static char input_str[] = "[.wrk]";
>>>> ...
>>>> input_dsc.dsc$w_length = sizeof(input_str);
>>>>
>>>> which I believe must be off by 1.
>>>>
>>>> It did not declare return type of main and it made all variables
>>>> global instead of local in main, which is valid C but not very
>>>> good C.
>>>>
>>>> Arne
>>>>
>>>>
>>> Ouch!
>>>
>>> Chris
>>>
>>
>>"Cut-n-Paste" usually means the user didn't bother to understand the
>>example/source. That isn't a good idea at any time. The doc examples
>>are to help one understand, not to be blindly copied.
>
>I wanted something quick to play with but copying it from Preview on my
>Mac to TextEdit produced put unadulterated garbage. What I don't under-
>stand is why the various macros (C-headers) were never added into the
>system's libraries. They need to be included from SYS$EXAMPLES. If the
>*include* files can be placed into SYS$EXAMPLES, why wasn't the example?
>After perusing that awful BACKUP API documentation, I whipped together a
>macro example. Far more readable too.
>
>If you want to wish you had a migraine a augmented by a hangover from a
>college toga party coupled with a raging case of herpes, take a gander
>at that BACKUP API documentation.

In fact, the only thing that I believe could be worse than that BACKUP
API documentation would be the .SDL that created the awful definitions
you see in SYS$EXAMPLES.

--
VAXman- A Bored Certified VMS Kernel Mode Hacker VAXman(at)TMESIS(dot)ORG

I speak to machines with the voice of humanity.

On 7/9/2021 8:25 PM, VAXman-@SendSpamHere.ORG wrote:
> In article <00B65888.594833A3@SendSpamHere.ORG>, VAXman- @SendSpamHere.ORG writes:
>> In article <sc86be$cvo$1@dont-email.me>, Dave Froble <davef@tsoft-inc.com> writes:
>>> On 7/8/2021 7:11 PM, Chris Townley wrote:
>>>> On 08/07/2021 23:53, Arne Vajhøj wrote:
>>>>> On 7/8/2021 5:42 PM, Chris Townley wrote:
>>>>>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>>>>>> On 7/8/2021 12:22 PM, VAXman-@SendSpamHere.ORG wrote:
>>>>>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>>>>>
>>>>>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>>>>>
>>>>>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>>>>>> very long while.
>>>>>>>
>>>>>>> I rewrote the example in the manual and ended up with:
>>>>>
>>>>>>> BACKUP/LIST look OK on the result.
>>>>>>>
>>>>>> Always beware of copying/pasting from Word or PDF - it usually does
>>>>>> strange things - especially with quotes!
>>>>>
>>>>> It was more than copy/paste problems.
>>>>>
>>>>> The example in the manual declared a function:
>>>>>
>>>>> unsigned int subtest(void *);
>>>>>
>>>>> without using it.
>>>>>
>>>>> It did:
>>>>>
>>>>> static char input_str[] = "[.wrk]";
>>>>> ...
>>>>> input_dsc.dsc$w_length = sizeof(input_str);
>>>>>
>>>>> which I believe must be off by 1.
>>>>>
>>>>> It did not declare return type of main and it made all variables
>>>>> global instead of local in main, which is valid C but not very
>>>>> good C.
>>>>>
>>>>> Arne
>>>>>
>>>>>
>>>> Ouch!
>>>>
>>>> Chris
>>>>
>>>
>>> "Cut-n-Paste" usually means the user didn't bother to understand the
>>> example/source. That isn't a good idea at any time. The doc examples
>>> are to help one understand, not to be blindly copied.
>>
>> I wanted something quick to play with but copying it from Preview on my
>> Mac to TextEdit produced put unadulterated garbage. What I don't under-
>> stand is why the various macros (C-headers) were never added into the
>> system's libraries. They need to be included from SYS$EXAMPLES. If the
>> *include* files can be placed into SYS$EXAMPLES, why wasn't the example?
>> After perusing that awful BACKUP API documentation, I whipped together a
>> macro example. Far more readable too.
>>
>> If you want to wish you had a migraine a augmented by a hangover from a
>> college toga party coupled with a raging case of herpes, take a gander
>> at that BACKUP API documentation.
>
> In fact, the only thing that I believe could be worse than that BACKUP
> API documentation would be the .SDL that created the awful definitions
> you see in SYS$EXAMPLES.
>

Many years ago I needed to do this. I took a look at the documentation,
then implemented a solution that created a small command file, then
spawned a sub-process to do the backup. Some things aren't worth the
aggravation.

--
David Froble Tel: 724-529-0450
Dave Froble Enterprises, Inc. E-Mail: davef@tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA 15486

On 7/9/2021 8:57 PM, Dave Froble wrote:
> On 7/9/2021 8:25 PM, VAXman-@SendSpamHere.ORG wrote:
>> In article <00B65888.594833A3@SendSpamHere.ORG>, VAXman-
>>> If you want to wish you had a migraine a augmented by a hangover from a
>>> college toga party coupled with a raging case of herpes, take a gander
>>> at that BACKUP API documentation.
>>
>> In fact, the only thing that I believe could be worse than that BACKUP
>> API documentation would be the .SDL that created the awful definitions
>> you see in SYS$EXAMPLES.
>
> Many years ago I needed to do this.  I took a look at the documentation,
> then implemented a solution that created a small command file, then
> spawned a sub-process to do the backup.  Some things aren't worth the
> aggravation.

That solution makes a lot of sense.

The DCL BACKUP command is a lot better documented and well known
than the BACKUP$ API.

The performance overhead of spawning a sub-process is likely
insignificant compared to doing the backup.

But maybe there are some funky security requirements that we don't
know about.

Arne

> ... whole thread expurated ...

This OpenVMS doc is poor, and this source code example is weak, and the
whole concept that folks won't be incorporating source code examples
into production code is just, well, wrong.

This source code incorporation happens ~everywhere. I'd expect there
are OpenVMS source code examples that have found their way back into
OpenVMS itself. And elsewhere.

Example source code needs to be complete and correct and with
functional error handling, needs to build correctly, and with a
copyright amenable to its incorporation into customer apps.

Because that incorporation is what is going to happen.

Would I like skilled development staff able to recognize latent issues
in (buggy) example source code? Sure. But if that were the case, I'd
wonder whether that skilled staff was even looking at the source code
examples.

And this incorporation happens. There are hunks of customer support
center example source code I've met in various different customer
engagements, and the source code itself is problematic at best.

That the customer support center was providing these examples isn't a
problem, but it does tend to point to issues in... to point to
opportunities for enhancements in OpenVMS and its APIs and
documentation and examples.

Then there's the whole discussion of the staggering about of source
code needed for an API call; all the glue code that's needed just to
use OpenVMS APIs. And the other whole discussion about the level of
abstraction provided by the existing OpenVMS APIs.

VSI has discussed providing ways to add user-provided source code into
OpenVMS. Source code examples would be one such area. But that's all
fodder for well after V9.2 is available and stable.

And a mea culpa specifically here: I'm responsible for the "" inclusion
stuff within BACKUP (and not the expected <> inclusions). I was asked
where to add some data structures and examples into OpenVMS, so I
answered. What I hadn't realized at the time was that those data
structures were the API. All that stuff should be in the public APIs,
not where it's located.

--
Pure Personal Opinion | HoffmanLabs LLC

> This source code incorporation happens ~everywhere. I'd expect there
> are OpenVMS source code examples that have found their way back into
> OpenVMS itself. And elsewhere.

Probably some similar process resulted in what I recount below.

I recall from a long-ago DECUS symposium (probably in an RSX "Magic Session") a DEC developer mentioning that there were scattered around the RSX sources (including libraries and utilities) redundant instances of the RAD50<->ASCII conversion code. ("Redundant" here meaning pointless. I can at least conceive of reasons why one component of the system might not be able to access the code instance in some other component.)

A wise guy in the audience (there were plenty of them in typical RSX Magic Sessions) replied, "That's so that if one copy of the code breaks, callers of the other non-broken copies won't be affected." I suppose an undetected memory error could lead to that... :-)

On 7/12/2021 1:56 PM, Galen wrote:
>> This source code incorporation happens ~everywhere. I'd expect there
>> are OpenVMS source code examples that have found their way back into
>> OpenVMS itself. And elsewhere.
>
> Probably some similar process resulted in what I recount below.
>
> I recall from a long-ago DECUS symposium (probably in an RSX "Magic Session") a DEC developer mentioning that there were scattered around the RSX sources (including libraries and utilities) redundant instances of the RAD50<->ASCII conversion code. ("Redundant" here meaning pointless. I can at least conceive of reasons why one component of the system might not be able to access the code instance in some other component.)
>
> A wise guy in the audience (there were plenty of them in typical RSX Magic Sessions) replied, "That's so that if one copy of the code breaks, callers of the other non-broken copies won't be affected." I suppose an undetected memory error could lead to that... :-)
>

I believe that was Brian McCarthy, doing a presentation at the RSX
Magic Session he called "You Paid For It", where he pointed out
redundant and crazy things in the RSX code base, that we the customers
had effectively paid for.

It was great.

--
Lee K. Gleason N5ZMR
Control-G Consultants
lee.gleason@comcast.net

On 7/14/2021 12:31 PM, jimc...@gmail.com wrote:
> On Thursday, July 8, 2021 at 5:47:45 PM UTC-7, Dave Froble wrote:
>
>> "Cut-n-Paste" usually means the user didn't bother to understand the
>> example/source. That isn't a good idea at any time. The doc examples
>> are to help one understand, not to be blindly copied.
>
> Cutting-and-pasting code into an editor so you can build and experiment is an important expedient even if you're going to rewrite and integrate independently.
>

Only if you understand what you're using.

--
David Froble Tel: 724-529-0450
Dave Froble Enterprises, Inc. E-Mail: davef@tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA 15486

On Wednesday, July 14, 2021 at 3:58:01 PM UTC-7, Dave Froble wrote:

> Only if you understand what you're using.

They're orthogonal points. Breaking cut-and-paste isn't going to make engineers more likely to do the right thing, and everyone deserves to be productive.

On 7/15/2021 12:06 PM, jimc...@gmail.com wrote:
> On Wednesday, July 14, 2021 at 3:58:01 PM UTC-7, Dave Froble wrote:
>
>> Only if you understand what you're using.
>
> They're orthogonal points. Breaking cut-and-paste isn't going to make engineers more likely to do the right thing, and everyone deserves to be productive.
>

I'd agree. I've used cut-n-paste many times. I knew what the code did,
I insured that it would be appropriate, and I tested to insure all that.
No sense re-typing what already exists, or can be easily modified for
the task.

However, I've had the misfortune to observe a few people who didn't have
a clue, and used cut-n-paste and didn't get anything meaningful
accomplished. Well, they did get to say "I worked on it", but things
would have been better if they hadn't.

These experiences are why I mention that first a programmer must
understand what is required, must understand what the source code
actually does, and uses the source code to accomplish the intended task.

I know that I'm talking about incompetents, but, that is who really
likes to use cut-n-paste.

--
David Froble Tel: 724-529-0450
Dave Froble Enterprises, Inc. E-Mail: davef@tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA 15486

On 2021-07-14 22:57:20 +0000, Dave Froble said:

> On 7/14/2021 12:31 PM, jimc...@gmail.com wrote:
>> On Thursday, July 8, 2021 at 5:47:45 PM UTC-7, Dave Froble wrote:
>>
>>> "Cut-n-Paste" usually means the user didn't bother to understand the
>>> example/source. That isn't a good idea at any time. The doc examples
>>> are to help one understand, not to be blindly copied.
>>
>> Cutting-and-pasting code into an editor so you can build and experiment
>> is an important expedient even if you're going to rewrite and integrate
>> independently.
>
> Only if you understand what you're using.

I'd like secure code. I'd like perfect code. I'd like folks that
understand all aspects of the code. Or every aspect of the enterprise
environment. All those are wonderful and desirable and all the rest.
But that isn't the world that most of us live in and operate in.

Cut-and-paste app development is how the world works now, and I'd wager
~everybody here has used existing copyright-appropriate source code
examples as a starting point.

Nobody is an expert in all of the OpenVMS APIs, and some of the OpenVMS
APIs can diverge widely (SMG, ACME, OpenSSL, etc) from the more typical
API designs.

The OpenVMS API designs are also wildly different from APIs on other platforms.

There are cases where the error handling is a central part of the call,
and existing OpenVMS examples tend to fail here. This includes BACKUP,
SSL/TLS, and a number of other contexts.

Copying cookbook code is how the world works now, how ~all of us
already or will be operating, and particularly with the sorts of
complex and glue-code-focused API designs prevalent on OpenVMS.

Template source code examples embedded directly in documentation are,
well, archaic. And in various cases, won't build, or will omit
important API details in the interest of brevity of documentation.

I'd prefer better abstractions in general, and I'd prefer the source
code examples be prepared as cookbooks with robust error handling, to
be buildable and usable, and with a permissive copyright. Let the docs
link to the cookbook.

I'll again dare y'all: I *DARE* you to write a client-server app using
a SSL/TLS connection with proper certificate verification on both ends
of the connection, including the ability to detect interception, using
the current TLSv1.3 and secure encryption and key exchange. I *DARE*
you. And this is just the tip of the difficulty. ACME is no great joy
to use for a password verification—what should be an easy case—as
another example. I won't dare y'all to write that, as you'll fail.

--
Pure Personal Opinion | HoffmanLabs LLC

On 7/10/2021 2:26 PM, Stephen Hoffman wrote:
> This OpenVMS doc is poor, and this source code example is weak, and the
> whole concept that folks won't be incorporating source code examples
> into production code is just, well, wrong.
>
> This source code incorporation happens ~everywhere. I'd expect there are
> OpenVMS source code examples that have found their way back into OpenVMS
> itself. And elsewhere.

Yep.

> Example source code needs to be complete and correct and with functional
> error handling, needs to build correctly, and with a copyright amenable
> to its incorporation into customer apps.

I don't think it is that simple.

A complete example makes it easy to copy paste and show some of the
extra stuff that need to be done in final code.

But a complete example also tend to be much bigger and taking
much more time to read than a snippet that only show the the
specific stuff the example need to illustrate.

So there are pros and cons of both. The copy paste people
prefer the complete example, but the read and understand
people probably prefer the short example.

And there are in between: code that is compilable but are still
not complete.

I am really fine with all flavors.

As long as it is clearly indicated what it is.

It is really bad to present example code as complete if it is
not complete.

And it is really bad to provide example code that does not work
without clearly explaining that it is really pseudo code.

But as long as the "label" match the "content" then it is up
to the reader to read.

Arne

On 7/15/2021 8:25 PM, Stephen Hoffman wrote:
> On 2021-07-14 22:57:20 +0000, Dave Froble said:
>
>> On 7/14/2021 12:31 PM, jimc...@gmail.com wrote:
>>> On Thursday, July 8, 2021 at 5:47:45 PM UTC-7, Dave Froble wrote:
>>>
>>>> "Cut-n-Paste" usually means the user didn't bother to understand the
>>>> example/source. That isn't a good idea at any time. The doc examples
>>>> are to help one understand, not to be blindly copied.
>>>
>>> Cutting-and-pasting code into an editor so you can build and
>>> experiment is an important expedient even if you're going to rewrite
>>> and integrate independently.
>>
>> Only if you understand what you're using.
>
> I'd like secure code. I'd like perfect code. I'd like folks that
> understand all aspects of the code. Or every aspect of the enterprise
> environment. All those are wonderful and desirable and all the rest. But
> that isn't the world that most of us live in and operate in.

You trying to say the world is imperfect?

> Cut-and-paste app development is how the world works now, and I'd wager
> ~everybody here has used existing copyright-appropriate source code
> examples as a starting point.

There is no sense in re-inventing the wheel, but, one should be sure the
wheel they intend to use is actually round, right?

> Nobody is an expert in all of the OpenVMS APIs, and some of the OpenVMS
> APIs can diverge widely (SMG, ACME, OpenSSL, etc) from the more typical
> API designs.

You do like to understate some issues, huh? Imagine, calling something
an IOSB when it's format is not the IOSB we all know and hate.

> The OpenVMS API designs are also wildly different from APIs on other
> platforms.

Not an issue for some of us.

> There are cases where the error handling is a central part of the call,
> and existing OpenVMS examples tend to fail here. This includes BACKUP,
> SSL/TLS, and a number of other contexts.
>
> Copying cookbook code is how the world works now, how ~all of us already
> or will be operating, and particularly with the sorts of complex and
> glue-code-focused API designs prevalent on OpenVMS.

I just cannot get too comfortable with that.

> Template source code examples embedded directly in documentation are,
> well, archaic. And in various cases, won't build, or will omit important
> API details in the interest of brevity of documentation.

Gee, you must have been attempting to read the TCP/IP docs ...

:-)

> I'd prefer better abstractions in general, and I'd prefer the source
> code examples be prepared as cookbooks with robust error handling, to be
> buildable and usable, and with a permissive copyright. Let the docs link
> to the cookbook.

Sort of like the older VMS documentation?

> I'll again dare y'all: I *DARE* you to write a client-server app using a
> SSL/TLS connection with proper certificate verification on both ends of
> the connection, including the ability to detect interception, using the
> current TLSv1.3 and secure encryption and key exchange. I *DARE* you.
> And this is just the tip of the difficulty. ACME is no great joy to use
> for a password verification—what should be an easy case—as another
> example. I won't dare y'all to write that, as you'll fail.

So what, you like to place your bets after the race is run, huh?

I looked at such, and quickly saw that it just wasn't gonna happen. So
I started placing custom checks on data. I can control that to some
extent. I cannot control the wildness of the web.

--
David Froble Tel: 724-529-0450
Dave Froble Enterprises, Inc. E-Mail: davef@tsoft-inc.com
DFE Ultralights, Inc.
170 Grimplin Road
Vanderbilt, PA 15486

In article <scpun6$7mm$1@dont-email.me>, Dave Froble
<davef@tsoft-inc.com> writes:

> I'd agree. I've used cut-n-paste many times. I knew what the code did,
> I insured that it would be appropriate, and I tested to insure all that.
> No sense re-typing what already exists, or can be easily modified for
> the task.
>
> However, I've had the misfortune to observe a few people who didn't have
> a clue, and used cut-n-paste and didn't get anything meaningful
> accomplished.

So, with regard to cut and paste, if they don't have a clue, they
shouldn't have the glue. :-)

On 2021-07-15 18:27:03 +0000, Dave Froble said:

> I know that I'm talking about incompetents, but, that is who really
> likes to use cut-n-paste.

Experienced folks too like having working examples and functional
templates to start from.

For many of us, a working example makes figuring out an API a whole lot easier.

And a working example with competent error handling, all the better.

This as compared with the current and antiquated morass found within
the existing OpenVMS documentation, and the examples directory. And the
VSI support database has some gaps.

We're unfortunately all incompetents in at least some parts of OpenVMS.

--
Pure Personal Opinion | HoffmanLabs LLC

On 7/16/2021 4:17 PM, Stephen Hoffman wrote:
> On 2021-07-15 18:27:03 +0000, Dave Froble said:
>
>> I know that I'm talking about incompetents, but, that is who really likes to
>> use cut-n-paste.
>
> Experienced folks too like having working examples and functional templates to
> start from.
>
> For many of us, a working example makes figuring out an API a whole lot easier.
>
> And a working example with competent error handling, all the better.

Against my better judgement, I'll make an effort to get better examples added
to SYS$EXAMPLES:, especially to replace ones that are broken.

Note that I'm not planning on looking for broken examples myself, nor do I plan
to fix any, but I will take submissions and do my best.

Go ahead and email them to me; don't just post 'em here.

--
-- Rob