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)

Logical 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 NS 3000/iX link, bit 2 (where bit 0 is the high-order bit) indicates which NS 3000 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 NS 3000/iX 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.




	NOTE: BREAK is disabled during a `DSCOPY` intrinsic operation. After `DSCOPY` completes, BREAK is re-enabled. If BREAK is programmatically disabled before the `DSCOPY` call, you must programmatically disable the BREAK again after the `DSCOPY` completes.

Programmatic examples may be found at the end of this chapter.

DSCOPY Intrinsic

Technical documentation

» Table of Contents

» Index

Syntax

Parameters

Description