Operating System BS2000 OS DX V1.0 (en)

&pagelevel(3)&pagelevel

Copy file from or to POSIX

Component:	POSIX-BC
Functional area:	File processing POSIX administration and application
Domain:	FILE
Privileges:	all privileges

Function

The COPY-POSIX-FILE command offers the functionality of the POSIX command bs2cp in BS2000:

Copying files from the POSIX file system to BS2000 files or elements of a PLAM library
Copying BS2000 files or elements of a PLAM library to the POSIX file system (library elements are only copied to simple files)

Access to BS2000 files via RFA (Remote File Access) is not supported. For encrypted files, the crypto password must be entered into the crypto password table (see the ADD-CRYPTO-PASSWORD command).

Notes on command execution

The specifications in the COPY-POSIX-FILE command generate a bs2cp command with the corresponding parameters (if a list of file names is specified, a corresponding number of bs2cp commands) which is called in a POSIX shell (see the START-POSIX-SHELL command). The caller must, therefore, have a HOME directory in POSIX. The settings from the profile in the HOME directory (e.g changing the current directory and values of the environment variables IO_CONVERSION and BS2CPTABS) affect the copy process.

Before the bs2cp command is called, two other POSIX commands may be issued if required:

The handling of text and binary files when copying (RECORD-CONVERSION operand) is controlled via an ftyp command.
The file attributes of the target files are optionally controlled via a bs2file command (FILE-ATTRIBUTES operand).

The POSIX command bs2cp is described in the “POSIX Basics for Users and System Administrators” manual [28], the bs2file and ft yp commands in the “POSIX Commands” manual [29].

The mode of operation of the COPY-POSIX-FILE command is described in detail in the “POSIX Basics for Users and System Administrators” manual [28].

Format

COPY-POSIX-FILE

Alias: CPXF/BS2CP

COPY-DIRECTION = FROM-POSIX / TO-POSIX
,POSIX-FILE = *BY-SOURCE(...) / list-poss(2000): <posix-pathname 1..1023>
	*BY-SOURCE(...)
		\|	POSIX-DIRECTORY = . / <posix-pathname 1..1023 without-wild>
		\|	,PREFIX = *NONE / <c-string 0..80 with-low>
		\|	,SUFFIX = *NONE / <c-string 0..80 with-low>
,BS2000-FILE = BY-SOURCE(...) / LIBRARY-ELEMENT(...) / list-poss(2000): <filename 1..54 with-wild(80)>
	*BY-SOURCE(...)
		\|	PREFIX = *NONE / <c-string 0..53>
		\|	,SUFFIX = *NONE / <c-string 0..40>
	*LIBRARY-ELEMENT(...)
		\|	LIBRARY = <filename 1..54>
		\|	,ELEMENT = *BY-SOURCE(...) / list-poss(2000): <composed-name 1..64 with-under-wild>(...)
		\|		*BY-SOURCE(...)
		\|			\|	VERSION = HIGHEST-EXISTING / UPPER-LIMIT / <composed-name 1..24 with-under>
		\|			\|	,PREFIX = *NONE / <c-string 0..63>
		\|			\|	,SUFFIX = *NONE / <c-string 0..63>
		\|		<composed-name 1..64 with-under-wild>(...)
		\|			\|	VERSION = HIGHEST-EXISTING / UPPER-LIMIT / <composed-name 1..24 with-under>
		\|	,TYPE = S / D / J / M / P / X / *L
,WRITE-MODE = BY-DIALOG / REPLACE / *CREATE
,CHARACTER-CONVERSION = NO / YES(...)
	*YES(...)
		\|	TABLE = *STD / <posix-pathname 1..1023 without-wild>
,OUTPUT = NONE / SYSOUT
,RECORD-CONVERSION = TEXT (...) / BINARY
	*TEXT (...)
		\|	SUBSTITUTE-TABULATOR = YES / NO
,FILE-ATTRIBUTES = STD / PARAMETER(...)
	*PARAMETER(...)
		\|	FILE-NAME = *ALL / <filename 1..54>
		\|	,ATTRIBUTES = *STD / <c-string 0..1000>

Operands

COPY-DIRECTION =
Copy direction.

COPY-DIRECTION = *FROM-POSIX
POSIX files are copied to BS2000.

COPY-DIRECTION = *TO-POSIX
BS2000 files or PLAM elements are copied to POSIX.

POSIX-FILE = *BY-SOURCE / list-poss(2000): <posix-pathname 1..1023>
Specifies the POSIX files to be used during copying.

POSIX-FILE = *BY-SOURCE
This specification is only possible when copying *TO-POSIX:
The names of the POSIX files should be derived from the BS2000 names. If multiple BS2000 files are to be copied to POSIX, this operand value must be specified.

POSIX-DIRECTORY =
Specifies the directory to which the BS2000 files or the PLAM elements are to be copied.

POSIX-DIRECTORY = .
The files are copied to the directory currently set.
As default, this is the home directory of the calling BS2000 user. Another current directory can be set by using the change directory command in the .profile file (with the POSIX command cd).

POSIX-DIRECTORY = <posix-pathname 1..1023 without-wild>
The files are copied to the explicitly specified directory.

PREFIX = *NONE / <c-string 0..80 with-low>
Prefix for the POSIX file name. *NONE is the default, i.e. no prefix is used.

SUFFIX = *NONE / <c-string 0..80 with-low>
Suffix for the POSIX file name. *NONE is the default, i.e. no suffix is use.

POSIX-FILE = list-poss(2000): <posix-pathname 1..1023>
The names of POSIX files are entered explicitly. The following must be taken into account:

When copying *FROM-POSIX:
Enter one or more absolute or relative path names of the POSIX files. The POSIX wildcard syntax (shell special characters for file name replacement) is supported.
When copying *TO-POSIX:
If only one BS2000 file is copied and the name of the target file is to be explicitly specified, the absolute or relative path name of a POSIX file must be specified. Wildcard syntax is not permitted.
As default, relative path names refer to the home directory of the calling BS2000 user. Another directory can be set by using the change directory (cd) command in the .profile file.

BS2000-FILE = *BY-SOURCE(...) / *LIBRARY-ELEMENT(...) / list-poss(2000): <filename 1..54 with-wild(80)>
Specifies the BS2000 files or the PLAM elements to be used during copying.

BS2000-FILE = *BY-SOURCE(...)
This specification is only possible when copying *FROM-POSIX:
The names of the BS2000 files are derived from the names of the POSIX files. This is a mandatory entry when more than one POSIX file is to be copied to BS2000.

PREFIX = *NONE / <c-string 0..53 with-low>
Prefix for the BS2000 file name. *NONE is the default, i.e. no prefix is used.

SUFFIX = *NONE / <c-string 0..40 with-low>
Suffix for the BS2000 file name. *NONE is the default, i.e. no suffix is use.

BS2000-FILE = *LIBRARY-ELEMENT(...)
PLAM elements are used during copying.

LIBRARY = <filename 1..54>
Name of the PLAM library.

ELEMENT =
Specifies the PLAM elements to be used during copying.

ELEMENT = *BY-SOURCE(...)
This specification is only possible when copying *FROM-POSIX:
The element name is to be derived from the POSIX name. This is a mandatory entry if more than one POSIX file is to be copied to a PLAM library in BS2000.

VERSION =
Specifies which version of an element is to be used.

VERSION = *HIGHEST-EXISTING
The target element with the highest version is used. The following must be taken into account:

- - If an element does not yet exist, it is assigned version 001.
  - If existing elements are copied, then the element is overwritten with the highest version.

VERSION = *UPPER-LIMIT
The target element should be assigned the highest possible version (X’FF’; this corresponds to the tilde character in the bs2cp command).

VERSION = <composed-name 1..24 with-under>
The version is explicitly entered.

PREFIX = *NONE / <c-string 0..63 with-low>
Prefix for the element file name. *NONE is the default, i.e. no prefix is used.

SUFFIX = *NONE / <c-string 0..63 with-low>
Suffix for the element file name. *NONE is the default, i.e. no suffix is used.

ELEMENT = list-poss(2000): <composed-name 1..64 with-under-wild>(...)
The names of the elements are entered explicitly. The following must be taken into account:

- - When copying *TO-POSIX:
    Enter one or more element names. The LMS wildcard syntax (“*”, “<“, “:”, “>”) is supported.
    In contrast to the POSIX command bs2cp a list of element names can also be specified here. In this case, the POSIX command bs2cp is called for each element name (with/without wildcard). The entries for the other operands then apply for all bs2cp calls.
  - When copying *FROM-POSIX:
    Explicit specification of an element name (wildcards are not allowed here) if only one POSIX file is copied and the name of the target element is to be defined explicitly.

VERSION =
Specifies the element version used.

VERSION = *HIGHEST-EXISTING
The element with the highest version is used.

VERSION = *UPPER-LIMIT
The copied element should be assigned the highest possible version (X’FF’).

VERSION = <composed-name 1..24 with-under>
The version is entered explicitly.

TYPE = *S / *D / *J / *M / *P / *X / *L
Specifies the type of PLAM elements handled. As default, the type S (Source) is used.

BS2000-FILE = list-poss(2000): <filename 1..54 with-wild(80)>
The names of the BS2000 files are entered explicitly. The following must be taken into account:

When copying *TO-POSIX:
Enter one or more file names. The BS2000 wildcard syntax is supported with restrictions (only the wildcard “*”).
In contrast to the POSIX command bs2cp a list of BS2000 file names can also be specified here. In this case, the POSIX command bs2cp is called for each file name (with/without wildcard). The entries for the other operands then apply for all bs2cp calls.
When copying *FROM-POSIX:
Explicit specification of a file name (wildcards are not allowed here) if only one POSIX file is copied and the name of the target file is to be defined.

WRITE-MODE =
This specification is only relevant when copying *FROM-POSIX.
Specifies whether target files or elements that already exist in BS2000 are overwritten (this is similar to the -f option in the POSIX command bs2cp).

WRITE-MODE = *BY-DIALOG
In this case the dialog will display a prompt asking if an existing file should be overwritten.

bs2cp: overwrite A ? y (yes), n (no), a (all) or q (quit)

WRITE-MODE = *REPLACE
The dialog prompt is suppressed and existing files or elements are always overwritten.

WRITE-MODE = *CREATE
Target files or elements which do not yet exist are created. Existing target files or elements are not overwritten.

CHARACTER-CONVERSION =
Specifies if character conversion can be carried out during the copying process (this is similar to the -k and -t options in the POSIX bs2cp command).

CHARACTER-CONVERSION = *NO
Character conversion is not carried out.

CHARACTER-CONVERSION = *YES(...)
Character conversion is carried out.

TABLE =
Specifies the conversion table.

TABLE = *STD
Internal POSIX default tables are used (this is similar to the -k option in the POSIX command bs2cp).

TABLE = <posix-pathname 1..1023 without-wild>
The conversion table is entered explicitly (this is similar to the -t option in the POSIX command bs2cp).

Note

The shell variable BS2CPTABS (see bs2cp) is not supplied with values via this specification. If required the variable in the .profile can be set.

OUTPUT =
Specifies whether extended logging of the bs2cp command is to be output (this is similar to the -l option in the POSIX command bs2cp).

OUTPUT = *NONE
The extended logging is not output.

OUTPUT = *SYSOUT
The extended logging is output to SYSOUT.

RECORD-CONVERSION =
Entry specifying how the contents of BS2000 files are to be handled during copying.
This parameter generates the POSIX command ftyp with the corresponding parameters. If an operand value is not explicitly specified (corresponds to the preset value RECORD-CONVERSION=*TEXT(SUBSTITUTE-TABULATOR=*YES)), ftyp text is set as the default.

RECORD-CONVERSION = *TEXT(...)
SAM files or PLAM library elements are handled as text files. “newline” in the POSIX file becomes a change of record in the BS2000 file (or vice versa, depending on the copying direction).

SUBSTITUTE-TABULATOR =
Specifies how tabulator characters are to be handled.

SUBSTITUTE-TABULATOR = *YES
Tabulator characters are to be filled (ftyp text).

SUBSTITUTE-TABULATOR = *NO
Tabulator characters are retained (ftyp textbin).

RECORD-CONVERSION = *BINARY
SAM files or PLAM library elements are handled as binary files.

FILE-ATTRIBUTES =
This specification is only relevant when copying *FROM-POSIX.
When POSIX files are copied to BS2000 (not for PLAM elements) the file attributes of the target files in BS2000 can be entered in the same way as for the POSIX command bs2file. Depending on the parameter entry, a bs2file command is issued in the shell before the actual bs2cp command.

FILE-ATTRIBUTES = *STD
No bs2file command is issued:
Files which do not yet exist are assigned the standard file attributes (SAM access method, variable record format, and standard blocking). Existing files retain their attributes. If only the catalog entry exists for a file (no OPEN has taken place), the ISAM access method is used.

FILE-ATTRIBUTES = *PARAMETER(...)
A bs2file command is issued when copying. The file attributes are specified in the same way as for the POSIX command bs2file.

FILE-NAME =
Specifies the file for which the attributes are to be set.

FILE-NAME = *ALL
The attributes entered are valid for the first file to be copied with any name (corresponds to the “*” entry in the POSIX command bs2file).

FILE-NAME = <filename 1..54>
The attributes entered are valid for the first file which is to be copied which has this name.

ATTRIBUTES =
Specifies the file attributes.

ATTRIBUTES = *STD
The standard file attributes are used.

ATTRIBUTES = <c-string 1..1000>
Explicit specification of the file attributes.
The file attributes supported are described for the POSIX command bs2cp (see the “POSIX Basics for Users and System Administrators” manual [28]). The entry format for the file attributes (operands and possible values) is described under the FILE macro (see the “DMS Macros” manual [12]).

Example: ATTRIBUTES='FCBTYPE=SAM,RECFORM=F,BLKSIZE=80'

Return codes

SC1	Maincode	Meaning
0	CMD0001	No errors
64	POS6010	Invalid combination of the specifications BS2000-FILE=BY-SOURCE and COPY-DIRECTION=TO-POSIX
64	POS6011	Invalid combination of hte specifications BS2000-FILE=LIBRARY-ELEMENT(...,ELEMENT=BY-SOURCE,...) and COPY-DIRECTION=*TO-POSIX
64	POS6012	Invalid combination of the specifications POSIX-FILE=BY-SOURCE and COPY-DIRECTION=FROM-POSIX
64	POS6013	More than one BS2000 file specified as target.
64	POS6014	More than one PLAM library element specified as target.
64	POS6015	More than one POSIX file specified as target.
64	POS6016	More than one BS2000 file or PLAM library element specified as source and one POSIX file specified as target; however, this is not a directory.
64	POS6017	More than one POSIX file specified as source, but BS2000-FILE=*BY-SOURCE not specified.
64	POS6018	The required version of SDF or SDF-P-BASYS is not installed.
64	POS6019	Error when starting the POSIX shell.
64	POS6020	Error when executing the POSIX command bs2cp.
64	POS6021	Invalid specification of FILE-ATTRIBUTES.
64	POS6022	Error when executing the POSIX command bs2file.
64	POS6023	Invalid specification of wildcards.
64	POS6024	Invalid specification in the ATTRIBUTES operand.

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

COPY-POSIX-FILE

Function

Notes on command execution

Format

Operands

Return codes