callable BACKUP example

[V***@SendSpamHere.ORG]

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.

[V***@SendSpamHere.ORG]

Post by V***@SendSpamHere.ORG
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. ;)

[Arne Vajhøj]

Post by V***@SendSpamHere.ORG
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

[Chris Townley]

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

#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

[Arne Vajhøj]

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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

[Chris Townley]

Post by Arne Vajhøj

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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.
unsigned int subtest(void *);
without using it.
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

[Dave Froble]

Post by Arne Vajhøj

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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.
unsigned int subtest(void *);
without using it.
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.

[Arne Vajhøj]

Post by Dave Froble

Post by Arne Vajhøj

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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.
unsigned int subtest(void *);
without using it.
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

[Stephen Hoffman]

... 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.

[Galen]

Post by Stephen Hoffman
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... :-)

[Lee Gleason]

Post by Galen

Post by Stephen Hoffman
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
***@comcast.net

[Arne Vajhøj]

Post by Stephen Hoffman
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.

Post by Stephen Hoffman
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

[V***@SendSpamHere.ORG]

Post by Dave Froble

Post by Arne Vajhøj

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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.
unsigned int subtest(void *);
without using it.
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.

[V***@SendSpamHere.ORG]

Post by V***@SendSpamHere.ORG

Post by Dave Froble

Post by Arne Vajhøj

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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.
unsigned int subtest(void *);
without using it.
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.

[Dave Froble]

Post by V***@SendSpamHere.ORG

Post by V***@SendSpamHere.ORG

Post by Dave Froble

Post by Arne Vajhøj

Post by Chris Townley

Post by Arne Vajhøj

Post by V***@SendSpamHere.ORG
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.

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.
unsigned int subtest(void *);
without using it.
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.

[Arne Vajhøj]

Post by V***@SendSpamHere.ORG

Post by V***@SendSpamHere.ORG
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

[[e-mail]]

Post by Dave Froble
"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.

[Dave Froble]

Post by ***@gmail.com

Post by Dave Froble
"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.

[[e-mail]]

Post by Dave Froble
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.

[Dave Froble]

Post by ***@gmail.com

Post by Dave Froble
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.

[Stephen Hoffman]

Post by Dave Froble
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.

[Robert A. Brooks]

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.

[Phillip Helbig (undress to reply)]

Post by Dave Froble
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. :-)

[Dave Froble]

Post by Dave Froble

Post by ***@gmail.com

Post by Dave Froble
"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.