HP 3000 Manuals HP 3000 Manuals
DSCOPY Intrinsic
Transfers or copies a file from one node to another (or within a single
node).
Syntax
______________________________________
| |
| DSCOPY ( opt,spec,result)|
______________________________________
Parameters
opt
(input)
16-bit integer, by reference. Enables/disables the primary output (to
$STDLIST) and determines whether to continue after first transfer
failure. The following bits of the opt parameter are significant (all
others are reserved):
bit 15 Used to determine whether DSCOPY should terminate after
the first transfer failure during a multiple transfer.
0 = attempt all transfers, even after a failure
1 = terminate DSCOPY after first failure
bit 14 Allows addition of a command file name in spec array
for multiple file transfer.
0 = disables use of command file
1 = enables use of command file
bit 13 Enables/disables primary output.
0 = primary output disabled
1 = primary output enabled
Recommended values:
0 All transfers attempted. Primary output disabled.
1 DSCOPY terminates after first failure. Primary output
disabled.
2 All transfers attempted. Use of command file spec
enabled. Primary output disabled.
3 DSCOPY terminates after first failure. Use of command
file spec enabled. Primary output disabled.
4 All transfers attempted. Use of command file spec
disabled. Primary output enabled.
5 DSCOPY terminates after first failure. Use of command
file spec disabled. Primary output enabled.
6 All transfers attempted. Use of command file spec
enabled. Primary output enabled.
7 DSCOPY terminates after first failure. Use of command
file spec enabled. Primary output enabled.
HP recommends that you use the aforementioned values. Note that although
other values can be used, they must be between 0 and 14 (decimal),
inclusive.
spec (input)
Character array, by reference. In the case of a single or generic
transfer request, this parameter should contain the DSCOPY transfer
specification in the same syntax as the DSCOPY command parameters. The
text should be ASCII characters terminated by a one-byte binary zero
(that is, the ASCII null character).
If this parameter contains the terminating zero (null character) only,
the copy request(s) will be read from a file with the formal designator
DSCOPYI (whose default is $STDIN, the session terminal). This is a way,
in addition to using "wildcard" characters, of specifying multiple
transfer requests. If DSCOPYI represents an actual file, it must be
unnumbered and its lines must not end with nulls (zeros).
The spec data type differs slightly from language to language. See
"Programming Language Considerations" below for data type definitions of
specific languages.
result(output)
Two-element array of 16-bit integers, by reference. Indicates the
outcome of the intrinsic call. The first word of the array indicates
whether or not the transfer was successful. A zero value signifies
success; a nonzero value indicates an NFT error. If the number is
positive, indicating an unsuccessful transfer over an NS3000/XL link, bit
2 (where bit 0 is the high-order bit) indicates which NS3000 error set
the error belongs to: the HP 3000-specific error set (on) or the generic
NFT error set (off). The lower-order bits give the actual NFT error
number in one or the other error set. Thus there are three NFT error
sets. The result parameter containing these error numbers is interpreted
correctly by the DSCOPYMSG intrinsic. Refer to the NS3000/XL Error
Messages Reference Manual for these error messages.
The second word of the array represents the number of files that were
successfully copied.
Description
The DSCOPY intrinsic copies one file into another, performing exactly the
same operations that the DSCOPY command performs. The source and target
files do not have to be on the same node, and the program that calls the
intrinsic does not have to be located on the same node as either of the
files.
The opt parameter determines: (1) whether or not primary output is
enabled , (2) whether to return after all transfers in a series have been
attempted or after the first unsuccessful transfer, and 3) whether the
file transfer will take place from DSCOPYI or from a designated command
file.
If a single or generic transaction is involved, the spec parameter can
contain the full text of the transfer specification, including all
parameters and options, terminated by an ASCII null character. A null
character (numeric zero) alone indicates that the transfer requests are
to be read from the DSCOPYI file.
The returned result parameter indicates whether or not the transfer was
successful. (All the parameters are required; DSCOPY is not
option-variable.)
This intrinsic does not return condition codes. Split stack calls are
not allowed.
Programmatic examples may be found at the end of this chapter.