COPY-POSIX-FILE

Copy files from BS2000 to the POSIX file system (and vice versa)

Domain:	FILE
Privileges:	all privileges

The BS2000 command /COPY-POSIX-FILE has the same functional scope as the bs2cp shell command plus some enhancements. The software required for the processing of this command is an installed version of SDF-P-BASYS or SDF-P version V2.2 or higher.

Hints for technical realization: The /COPY-POSIX-FILE command parameters are mapped to the parameters of the bs2cp shell command. After the POSIX shell is accessed (with /START-SHELL), the bs2cp command is called. This means that the calling user must have a HOME directory in POSIX in order to use the command /COPY-POSIX-FILE and that the copying process is affected by the settings in the .profile of this HOME directory (see “Control of the copying process via the .profile file”).

The command makes it possible to copy files or PLAM library elements from BS2000 into the POSIX file system (as plain files, not as elements of ar libraries) and also to copy POSIX files into BS2000. The source files can be entered explicitly or with wildcard syntax. With POSIX files, the POSIX wildcard syntax is supported. With BS2000 files, however, only a limited BS2000 wildcard syntax (only “*”) is supported. With PLAM elements, the PLAM wildcard syntax is supported.

If only a single file is copied, you can enter the name of the target file explicitly. If you are copying several files, the names of the target files are explicitly derived from the names of the source files (see parameter *BY-SOURCE). If several source files are entered, then the target files are given the same names as the source files and the target files may take a suffix and a prefix. You should exercise caution when copying from POSIX to BS2000 if the POSIX file has an exotic name which is permitted in POSIX but is not supported in BS2000.

You can prevent the accidental overwriting of existing BS2000 files or PLAM library elements by using the WRITE-MODE parameter.

The conversion of file contents can be controlled through the CHARACTER-CONVERSION parameter (analogous to the options -k and -t of the shell command bs2cp).

Control of the message output is also possible.

Two other commands are closely related to the shell command bs2cp: these are bs2file and ftyp.

The bs2file command generates a FILE macro in BS2000 from the shell, thereby creating a file in BS2000 which has the required properties. Here, the parameter FILE-ATTRIBUTES has been introduced which is supposed to carry the parameters of the shell command bs2file.

The command ftyp is used during copying of text or binary files from BS2000 to POSIX (and vice versa) to indicate whether the files should be treated as text files or binary files. Hence, the parameter RECORD-CONVERSION is introduced which can take the corresponding values of the shell command ftyp (see description in "POSIX Commands" [1] manual). The parameter is only valid for the current SDF command call.

BS2CP and CPXF are alias names.

bs2file command support via the FILE-ATTRIBUTES parameter

The bs2file command can be issued in the shell before the bs2cp command. This makes it possible to define the type of BS2000 file because the string given with bs2file implicitly issues a FILE macro when bs2cp is called. To enable this, the parameter values are written to the .bs2cp file. The FILE-ATTRIBUTES parameter controls if (and with which parameters) the bs2file command is to be issued before the bs2cp command.

This parameter only needs to be entered during copying to BS2000 (*FROM-POSIX) and is only required if plain files and not PLAM libraries are to be processed.

Handling of redirections

If a redirection of SYSOUT to a file is performed before the COPY-POSIX-FILE call, you should note the following points to ensure meaningful processing:

• If the command is running in dialog mode, the redirection of SYSOUT to a file should be done with the following parameters of the ASSIGN-SYSOUT command:

  /ASSIGN-SYSOUT TO = <file >, TERMINAL-DISPLAY = *YES

  This will ensure that all messages described in the file will also be output to a terminal. This is especially important for messages which require an acknowledgement.

• If the default value

  TERMINAL DISPLAY = *NO

  is used instead, no prompt, but an asterisk (*) will appear on the screen which requires an input. This should be avoided for obvious reasons.

  This does not affect the WRITE-MODE parameter which defines if the file is to be overwritten as a new file or if the data is to be appended at the end of the file. To achieve the desired effect, the parameter must be set accordingly.

For the call of this command in a batch procedure, these precautions are not necessary.

EXIT value during incorrect processing of a COPY-POSIX-FILE

The processing of the /COPY-POSIX-FILE command is performed in three steps :

1. First, SDF syntax check is activated. This checks for any violations of syntax rules. If a violation is found, SDF outputs an error message and command processing is aborted.

2. Next, an SDF procedure with the syntactically correct parameters is called. This step consists of a semantic check. If the check is successful, the bs2cp shell command with the currently specified parameters is generated. In the event of an error (the syntax allows the explicit entry of two POSIX files which can be copied to three explicitly entered BS2000 files), the procedure will be terminated with an error code. This also applies if the loaded version of SDF does not match or if bs2cp cannot be started (see the error messages POS6010 through POS6019).

3. When the shell command bs2cp ... is executed, errors during the processing of /COPY-POSIX-FILE may still occur. If an error does occur, bs2cp will be ended with an exit value not equal to zero which is output in the message POS6020. If several files are being copied during the bs2cp call and an error occurs during the copying of one file (exit value not equal to zero), the copying continues with the remaining files.

If a bs2file command was issued, it is treated as follows:

• If a bs2file command is issued, the parameters entered previously will be checked for correctness by generating a FILE macro with *DUMMY. In the event of an error, a message is output and processing is terminated.

• If, in certain cases, a bs2file command is issued before the bs2cp call, the command's EXIT status will be saved and output later.

Control of the copying process via the .profile file

During the use of the SDF command COPY-POSIX-FILE, the actual copying is done in the shell with bs2cp. Hence, the settings in the .profile file of the calling user will also affect the copying process. Examples of relevant settings are:

• Changing the current directory (cd command). By default, the current directory is the home directory of the calling user.

• Defining the bs2cp-specific environment variables IO_CONVERSION and BS2CPTABS.

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..80 with-wild>
	*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 =

Direction of copying process.

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 =
Specifies the POSIX files to be used during copying.

POSIX-FILE = *BY-SOURCE
The names of the POSIX files are derived from the BS2000 names.

This is a mandatory entry when the copying direction is *TO-POSIX and more than one BS2000 file is to be copied.

This is an alternative entry to posix-pathname when the copying direction is *TO-POSIX, only one BS2000 file is to be copied and the name of the target file is to be derived from the name of the BS2000 file.

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

POSIX-DIRECTORY = .
The current directory is used.

By default, this is the home directory of the calling BS2000 user. A different current directory can be set using the change directory (cd) command in the .profile file.

POSIX-DIRECTORY = <posix-pathname 1..1023 without-wild>
The explicitly entered directory is used.

PREFIX =
Specifies the prefix which precedes the POSIX file name.

PREFIX = *NONE
No prefix is used.

PREFIX = c-string 0..80 with-low>
The string entered is used as prefix.

SUFFIX =
Specifies the suffix which is attached to the POSIX file name.

SUFFIX = *NONE
No suffix is used.

SUFFIX = <c-string 0..80 with-low>
The string entered is used as suffix.

POSIX-FILE = list-poss(2000): <posix-pathname 1..1023>
The names of POSIX files are entered explicitly. Plaese note the following:

• With the copying direction *FROM-POSIX, enter one or more absolute or relative path names of POSIX files. To specify the POSIX file name, the wildcard syntax (shell special characters for file name replacement) is supported.

• With the copying direction *TO-POSIX, when only a single BS2000 file is to be copied and the name of the target file is to be explicitly specified, enter the absolute or relative path name of a POSIX file. Wildcard syntax is not allowed.

• By default, relative path names refer to the home directory of the calling BS2000 user. A different directory can be set using the change directory (cd) command in the .profile file.

BS2000-FILE =
Specifies the BS2000 files or the PLAM elements to be used during copying.

BS2000-FILE = *BY-SOURCE(...)
The names of the BS2000 files are derived from the names of the POSIX files.

This is a mandatory entry when the copying direction is *FROM-POSIX and more than one POSIX file is to be copied.

This is an alternative entry to filename when the copying direction is *FROM-POSIX, only one POSIX file is to be copied and the name of the target file is to be derived from the name of the POSIX file.

PREFIX =
Specifies the prefix which precedes the BS2000 file names.

PREFIX = *NONE
No prefix is used.

PREFIX = <c-string 0..53 with-low>
The string entered is used as prefix.

SUFFIX =
Specifies the suffix to be attached to the BS2000 files names.

SUFFIX = *NONE
No suffix is used.

SUFFIX = <c-string 0..40 with-low>
The indicated string is used as suffix.

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

LIBRARY = <filename_1..54>
Explicit entry of the PLAM library to be used during copying.

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

ELEMENT = *BY-SOURCE(...)
The names of the elements are derived from the POSIX files.

This is a mandatory entry when the copying direction is *FROM-POSIX and more than one POSIX file is to be copied.

This is an alternative entry to composed-name when the copying direction is *FROM-POSIX, only one POSIX file is to be copied and the name of the target element is to be derived from the name of the POSIX file.

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

VERSION = *HIGHEST-EXISTING
The element with the highest version is used. Please note the following:

• If an element does not yet exist, it is assigned version 001.

• If existing elements are copied, the element with the highest version is overwritten.

VERSION = *UPPER-LIMIT
The copied element is to 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 =
Specifies the prefix which precedes the PLAM element names.

PREFIX = *NONE
A prefix is not used.

PREFIX = <c-string 0..63 with-low>
The string entered is used as prefix.

SUFFIX =
Specifies the suffix to be attached to the PLAM element name.

SUFFIX = *NONE
No suffix is used.

SUFFIX = <c-string 0..63 with-low>
The string entered is used as suffix.

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

• With the copying direction *TO-POSIX, enter one or more element names. To specify element names, the LMS wildcard syntax (“*”, “<”, “:”, “>”) is supported. The specification of a list of LMS file names (list-poss) is an extension to the bs2cp command where only one PLAM element operand (bs2:) is possible. When a file name list is specified, the bs2cp command is called for each file name (with or without wildcards). In this case, the specifications in the remaining SDF parameters are valid for all bs2cp calls.

• With the copying direction *FROM-POSIX, when only one POSIX file is to be copied and the name of the target file is to be explicitly specified, enter the explicit name of an element. Wildcard syntax is not allowed.

  VERSION =
  Specifies the element version used.

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

  VERSION = *UPPER-LIMIT
  The copied element is to 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. By default, the type S (Source) is used.

BS2000-FILE = list-poss (2000): <filename 1..80 with-wild>
The names of the BS2000 files are entered explicitly. Please note the following:

• With the copying direction *TO-POSIX, enter one or more DVS file names. To specify the file name, the wildcard syntax for DVS files (“*”) is supported. The specification of a list of DVS file names (list-poss) is an extension to the bs2cp command where only one file name operand (bs2:) is possible. When a file name list is specified, the bs2cp command is called for each file name (with or without wildcards). In this case, the specifications in the remaining SDF parameters are valid for all bs2cp calls.

• With the copying direction *FROM-POSIX, when only one POSIX file is to be copied and the name of the target file is to be explicitly specified, enter the explicit name of a DVS file. Wildcard syntax is not allowed.

WRITE-MODE =
Specifies if BS2000 files are overwritten during the copying process. The specification of WRITE-MODE = is only relevant when the copying direction is *FROM-POSIX. It specifies whether or not existing BS2000 files (DVS files or PLAM elements) can be overwritten (this is analogous to the -f option in the bs2cp command).

WRITE-MODE = *BY-DIALOG
The user will be prompted if an existing file should be overwritten.

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

WRITE-MODE = *CREATE
The dialog prompt is suppressed. Already existing files are not overwritten but new files are created.

CHARACTER-CONVERSION =
Specifies if conversion should be performed during the copying process (this is analogous to the -k and -t options in the bs2cp command, see the POSIX “Commands (Related publications )“ manual [1]).

CHARACTER-CONVERSION = *NO
Conversion is not performed.

CHARACTER-CONVERSION = *YES(...)
Conversion is performed.

TABLE =
Specifies the conversion table.

TABLE = *STD
POSIX-internal default tables are used (this is analogous to the -k option in the bs2cp command, see the POSIX “Commands (Related publications )“ manual [1]).

TABLE = <posix-pathname 1..1023 without-wild>
The conversion table is entered explicitly (this is analogous to the -t option in the bs2cp command, see the POSIX “Commands (Related publications )“ manual [1]).

Note

The value of the BS2CPTABS shell variable (see bs2cp) is not controlled via the SDF parameter. If necessary, it can be supplied in the .profile file.

OUTPUT =
Specifies if the bs2cp extended logging is to be output (this is analogous to the -l option of the bs2cp command, see the POSIX “Commands (Related publications )“ manual [1]).

OUTPUT = *NONE
Extended logging will not be output.

OUTPUT = *SYSOUT
Extended logging will be output to SYSOUT.

RECORD-CONVERSION =
Specifies how the contents of BS2000 files are to be treated during copying.

This parameter generates the ftyp shell command with corresponding parameters. If the parameter RECORD-CONVERSION is not explicitly specified, ftyp text is set by default.

RECORD-CONVERSION = *TEXT(...)
SAM files are treated as text files. The “newline” character is converted to “new record”.

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

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

SUBSTITUTE-TABULATOR = *NO
Tabulator characters are to be preserved (ftyp textbin).

RECORD-CONVERSION = *BINARY
SAM files are treated as binary files.

FILE-ATTRIBUTES =
When copying POSIX files to BS2000 as DVS files (not as PLAM elements), the file attributes are specified according to the shell command bs2file. Depending on the parameter entered, a bs2file command is issued in the shell before the actual bs2cp command call.

FILE-ATTRIBUTES = *STD
No bs2file shell command is issued during copying.

DVS files not yet existing are assigned the standard attributes FCBTYPE=SAM, RECFORM=V and BLKSIZE=STD. If already existing DVS files are overwritten, their file properties are kept. If only one catalog entry exists for a DVS file (without FCBTYPE, RECFORM, BLKSIZE), the file is assigned the standard attributes of the operating system (FCBTYPE=ISAM).

FILE-ATTRIBUTES = *PARAMETER(...)
During copying, the file attributes are specified in the same way as for the shell command bs2file.

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

FILE-NAME = *ALL
The attributes entered are valid for all files to be copied with an arbitrary name (corresponds to the “*” entry in the bs2file command).

FILE-NAME = <filename 1..54>
The attributes indicated are valid for the file with the specified name.

ATTRIBUTES =
Specifies the attributes in the (ISP-)FILE command format.

ATTRIBUTES = *STD
Standard attribute with the values: FCBTYPE = SAM, RECFORM = V, BLKSIZE = STD.

ATTRIBUTES = <c-string_1..1000>
Explicitly entry of attributes.

The supported file attributes are listed in the bs2cp shell command description (see the POSIX “Commands (Related publications )“ manual [1], section “Attributes supported by DVS files”).

Example

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

Command return codes

(SC2)	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 the 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.