The macro CALL "NCOPY"... can be used to transfer a file or library member. The local system can be the sender or receiver of the file. The local system is considered to be the system in which the call is initiated. The partner system is the remote system. The functionality corresponds to that of the command TRANSFER-FILE (NCOPY).
Macro
The function can be called as follows:
CALL "NCOPY" USING FT-NCOPY-LIST FT-RETURN-INFO.
FT-NCOPY-LIST
The range FT-NCOPY-LIST describes the parameter list for the NCOPY macro. FT-NCOPY-LIST must be defined in the WORKING-STORAGE SECTION and can be copied to there with the statement
COPY FTNCOPY [OF linkname].
Before the first NCOPY macro, the parameter fields should be deleted with the statement
MOVE LOW-VALUE TO USER-PARAMETERS IN FT-NCOPY-LIST.
Before executing another NCOPY macro, you must fill the desired fields. If a parameter is not specified or the default value is to be used, this field must be assigned the value LOW-VALUE.
FT-NCOPY-LIST is defined as follows:
01 FT-NCOPY-LIST.
*
02 FILLER PIC X(4) VALUE "1000".
*
02 USER-PARAMETERS.
*
05 TRANSFER-DIRECTION PIC X(1).
88 TO-PARTNER VALUE "T".
88 FROM-PARTNER VALUE "F".
*
05 PARTNER-NAME PIC X(200).
*
05 LOCAL-PARAMETER.
10 FILE-NAME PIC X(512).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 LINK-NAME PIC X(8).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 LIBRARY PIC X(56).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 ELEMENT PIC X(64).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 TYP PIC X(8).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 VERSION PIC X(24).
88 STD VALUE LOW-VALUE.
10 FILE-PASSWORD PIC X(11).
10 SUCCESS-PROCESSING PIC X(500).
10 FAILURE-PROCESSING PIC X(500).
10 USER-DEF-ADMISSION PIC X(67).
88 NONE VALUE LOW-VALUE.
10 TRANSFER-ADMISSION.
15 USER-ID PIC X(8).
15 ACCOUNT PIC X(40).
15 PASSWORD PIC X(35).
10 PROCESSING-ADMISSION.
88 NOT-SPECIFIED VALUE HIGH-VALUE.
15 USER-ID PIC X(8).
15 ACCOUNT PIC X(40).
15 PASSWORD PIC X(35).
10 LISTING PIC X(1).
88 SYSLST-LST VALUE LOW-VALUE.
88 LISTFILE VALUE "L".
88 SYSLST-FAIL VALUE "S".
88 LISTFILE-FAIL VALUE "E".
88 NONE VALUE "N".
10 MONJV PIC X(56).
88 NONE VALUE LOW-VALUE.
10 JV-PASSWORD PIC X(11).
88 NONE VALUE LOW-VALUE.
10 CODE-CHARACTER-SET PIC X(8).
88 STD VALUE LOW-VALUE.
*
05 REMOTE-PARAMETER.
10 REMOTE-SYNTAX PIC X(1).
88 BS2000 VALUE LOW-VALUE.
88 MSP VALUE "3".
88 ANY-SYNTAX VALUE "A".
10 FILE-NAME PIC X(512).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 LINK-NAME PIC X(8).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 LIBRARY PIC X(59).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 ELEMENT PIC X(67).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 TYP PIC X(11).
88 NOT-SPECIFIED VALUE LOW-VALUE.
10 VERSION PIC X(27).
88 NONE VALUE LOW-VALUE.
88 STD VALUE " ".
10 FILE-PASSWORD PIC X(131).
10 CREATE-PASSWORD PIC X(131).
10 SUCCESS-PROCESSING PIC X(500).
10 FAILURE-PROCESSING PIC X(500).
10 USER-DEF-ADMISSION PIC X(67).
88 NONE VALUE HIGH-VALUE.
10 TRANSFER-ADMISSION.
88 NONE VALUE HIGH-VALUE.
15 USER-ID PIC X(67).
15 ACCOUNT PIC X(64).
15 PASSWORD PIC X(131).
10 PROCESSING-ADMISSION.
88 NOT-SPECIFIED VALUE HIGH-VALUE.
88 NONE VALUE HIGH-VALUE.
15 USER-ID PIC X(67).
15 ACCOUNT PIC X(64).
15 PASSWORD PIC X(131).
10 FILE-AVAILABLE PIC X(1).
88 NONE VALUE LOW-VALUE.
88 IMMEDIATE VALUE "I".
88 DEFERRED VALUE "D".
10 STORAGE-ACCOUNT PIC X(40).
88 NONE VALUE LOW-VALUE.
10 ACCESS-MODE PIC X(1).
88 NONE VALUE LOW-VALUE.
88 PAR VALUE "P".
10 READ-FILE PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 REPLACE-FILE PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 EXTEND-FILE PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 READ-ATTRIBUTES PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 CHANGE-ATTRIBUTES PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 DELETE-FILE PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 INSERT-DATA-UNIT PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 ERASE-DATA-UNIT PIC X(1).
88 NO-VALUE VALUE LOW-VALUE.
88 NO-PAR VALUE "N".
88 YES VALUE "Y".
10 LEGAL-QUALIFICATION PIC X(80).
88 UNCHANGED VALUE LOW-VALUE.
10 CODE-CHARACTER-SET PIC X(8).
88 STD VALUE LOW-VALUE.
*
05 COMPRESS PIC X(1).
88 NONE VALUE LOW-VALUE.
88 BYTE-REPETITION VALUE "B".
88 ZIP VALUE "Z".
88 NONE-ENCRYES VALUE "E".
88 BYTE-ENCRYES VALUE "F".
88 ZIP-ENCRYES VALUE "G".
88 NONE-ENCRODI VALUE "O".
88 BYTE-ENCRODI VALUE "P".
88 ZIP-ENCRODI VALUE "R".
*
05 WRITE-MODE PIC X(1).
88 REPLACE-FILE VALUE LOW-VALUE.
88 NEW-FILE VALUE "N".
88 EXTEND-FILE VALUE "E".
*
05 DATA-TYPE PIC X(1).
88 CHARACTER-TYPE VALUE LOW-VALUE.
88 BINARY-TYPE VALUE "B".
88 USER-TYPE VALUE "C".
88 CHAR-STD-TYPE VALUE "D".
88 BIN-STD-TYPE VALUE "E".
88 NOT-SPECIFIED VALUE HIGH-VALUE.
*
05 PRIORITY PIC X(1).
88 NORMAL VALUE LOW-VALUE.
88 HIGH VALUE "H".
88 LOW VALUE "L".
*
05 START-TIME.
10 EARLIEST-DATE PIC X(8).
88 TODAY VALUE LOW-VALUE.
88 TOMORROW VALUE "T".
10 EARLIEST-TIME PIC X(5).
*
05 CANCEL-PARAMETER.
10 CANCEL-DESIRED PIC X(1).
88 NO-CANCEL VALUE LOW-VALUE.
88 YES VALUE "Y".
10 CANCEL-DATE PIC X(8).
88 TODAY VALUE LOW-VALUE.
88 TOMORROW VALUE "T".
10 CANCEL-TIME PIC X(5).
*
05 RECORD-SIZE PIC X(5).
88 NOT-SPECIFIED VALUE LOW-VALUE.
*
05 RECORD-FORMAT PIC X(1).
88 STD VALUE LOW-VALUE.
88 VARIABLE VALUE "V".
88 FIXED VALUE "F".
88 UNDEFINED VALUE "U".
An NCOPY macro does not modify any values in the structure FT-NCOPY-LIST.
The fields are to be written with left-justified characters and filled with right-justified blanks (default for the COBOL-MOVE statement for character strings).
Fields which should not contain any specifications are to be assigned LOW-VALUE.
If a parameter is not entered, the default values are generated as in the TRANSFER-FILE(NCOPY) command.
The version specification at the beginning of the structure FT-NCOPY-LIST serves to identify the COPY element and must not be overwritten.
With partners of the type MSP/MVS (REMOTE-SYNTAX:"3"), the filename is to be set in quotation marks if it contains the user ID (prefix).
All other values which should be set in quotation marks at the command interface do not have these quotation marks in the programming interface. For historical reasons, the value is converted to lower-case when USER-DEF-ADMISSION is specified without quotation marks. If the USER-DEF-ADMISSION is to be kept in its original form, it must be enclosed in quotation marks.
Passwords with integer values must be entered in binary form.
Specifications for the remote system which are taken by default from the specifications for the local system using *SAME in the TRANSFER-FILE(NCOPY) command must be explicitly entered at the COBOL interface.
Description of the data fields
Most parameters for FT-NCOPY-LIST have the same names and functions as the corresponding operands for the TRANSFER-FILE(NCOPY) command. Therefore, only the deviations will be explained here. Please refer to the corresponding command description in the manual "openFT (BS2000) - Command Interface " for the other explanations.
In addition to the options offered at the command interface, you can also address filenames and library names in COBOL programs via link names. To do this, use the field LINK-NAME in FT-NCOPY-LIST.
Only the link name or the filename/library name (not both) may be specified for a system (local or remote).
The remote filename or library name may only be specified via the link name if the local and remote systems are identical (file transfer with the same computer). If this rule is not observed, openFT will not recognize it and this will lead to undesired results.
If the file or library is specified using its link name, a missing specification for the remote file will be filled using the local filename. A link name which is not assigned at execution time leads to the message
FILE UNKNOWN.The field USER-DEF-ADMISSION in FT-NCOPY-LIST is only required, if the add-on product openFT-AC is used in the system and an admission profile is being addressed. In this case USER-DEF-ADMISSION can be used to enter the transfer admission required for this admission profile (the TRANSFER-ADMISSION in the command).
The field REMOTE-SYNTAX controls the syntax check of the entries for the remote system. It corresponds to the entry which you can make in front of the parentheses at the beginning of the REMOTE-PARAMETER in the command. If this field is also assigned the value LOW-VALUE or “3”, openFT runs a syntax check of these specifications according to the BS2000 or MVS syntax rules.
The options for the field START-TIME correspond to those of the command operand START. EARLIEST-DATE sets the earliest date and EARLIEST-TIME sets the earliest time for the start of the file transfer.
CANCEL-PARAMETER corresponds to the command operand CANCEL. You can use CANCEL-DESIRED to cancel your request while CANCEL-DATE and CANCEL-TIME allow you to specify the required time and date of cancellation.
Example NCOPY
******************************************************************
* EXAMPLE: *
* SUBMISSION OF A FILE TRANSFER REQUEST *
* *
* /TRANSFER-FILE PARTNER=VAR001,TRANS=TO, - *
* / LOC=(FILE=LOCFILE,TRANS=(USERID,ACCOUNT,'PASSWORD')),- *
* / REM=(FILE=REMFILE,TRANS=(USERID,ACCOUNT,'PASSWORD')) *
* *
* FROM A COBOL PROGRAM *
******************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. NCO.
*
ENVIRONMENT DIVISION.
*
CONFIGURATION SECTION.
SPECIAL-NAMES.
TERMINAL IS TERM.
*
DATA DIVISION.
WORKING-STORAGE SECTION.
77 MAIN-RCODE-STRING PIC -ZZZZ9.
77 SUB-RCODE-STRING PIC -ZZZZ9.
COPY FTNCOPY OF FTLIB.
COPY FTRETC OF FTLIB.
*
PROCEDURE DIVISION.
STEUER SECTION.
ST-01.
*
*SPECIFY PARAMETERS.
MOVE LOW-VALUE TO USER-PARAMETERS IN FT-NCOPY-LIST.
MOVE "VAR001" TO PARTNER-NAME.
MOVE "T" TO TRANSFER-DIRECTION.
MOVE "LOCFILE" TO FILE-NAME IN LOCAL-PARAMETER.
MOVE "USERID" TO USER-ID IN TRANSFER-ADMISSION
IN LOCAL-PARAMETER.
MOVE "ACCOUNT" TO ACCOUNT IN TRANSFER-ADMISSION
IN LOCAL-PARAMETER.
MOVE "'PASSWORD'" TO PASSWORD IN TRANSFER-ADMISSION
IN LOCAL-PARAMETER.
MOVE "REMFILE" TO FILE-NAME IN REMOTE-PARAMETER.
MOVE "USERID" TO USER-ID IN TRANSFER-ADMISSION
IN REMOTE-PARAMETER.
MOVE "ACCOUNT" TO ACCOUNT IN TRANSFER-ADMISSION
IN REMOTE-PARAMETER.
MOVE "'PASSWORD'" TO PASSWORD IN TRANSFER-ADMISSION
IN REMOTE-PARAMETER.
*
*NCOPY-CALLING.
CALL "NCOPY" USING FT-NCOPY-LIST FT-RETURN-INFO.
*
*RESULT HANDLING.
IF OKAY IN MAIN-RETURN-CODE
DISPLAY "NCOPY-REQUEST ACCEPTED, TID= " TRANSFER-ID
UPON TERM
ELSE
MOVE MAIN-RETURN-CODE TO MAIN-RCODE-STRING
MOVE SUB-RETURN-CODE TO SUB-RCODE-STRING
DISPLAY "NCOPY-REQUEST REJECTED" UPON TERM
DISPLAY "MAIN-RETURN-CODE: " MAIN-RCODE-STRING
" SUB-RETURN-CODE: " SUB-RCODE-STRING
UPON TERM.
ST-99.
STOP RUN.