Send File API

This API issues the Send File for the specified file ID.

In the case of instant transfer, this API issues the Send File request for instant transfer for the specified send file and receiving-side host.

Since the API works in Language Environment (LE), the CEE.SCEERUN Language Environment library is required. (This is the default name if the library name is defaulted during the installation of the operating system.)

= Remarks =

This API does not support use of the Send File in the Synchronous Transfer mode.

Call Format (COBOL)

CALL 'XRSNDAP'  USING  parameter area

Explanation of parameter area

The following tables show the fields of the parameter areas. Note that the fields differ when you use the Send File API for instant transfer. For the fields to specify in the parameter area when you carry out instant transfer, refer to Table 7.2 .

Table 7.1 Parameter area for the Send File API
Field	Attribute	Length	Input/Output	Description
Operating Version	Character	6	Input	Specify the version of the parameter area. Specify one of the following: V08L01 V08L02 V08L04 The operation is the same regardless of which you specify.
File ID in the Send Management Information	Character	50	Input	Specify the file ID for the Send Request.
Status Code	Binary	2	Output	The API sets a status code in this field when the API ends.
Detail Code	Binary	2	Output	The API sets a detail code in this field when the API ends.

Table 7.2 Parameter area for the Send File API when you carry out instant transfer
Field	Attribute	Length	Input/Output	Description
Operating Version	Character	6	Input	Specify the version of the parameter area. Specify the following: V08L04
Send File ID	Character	50	Input	Do not specify this field.
Status Code	Binary	2	Output	The API sets a status code in this field when the API ends.
Detail Code	Binary	2	Output	The API sets a detail code in this field when the API ends.
Send File Name	Character	44	Input	Specify the send file.
Host Name	Character	50	Input	Specify the host name of the receiving-side host.
Port No.	Binary	4	Input	This parameter specifies the port number of the receiving-side host. (Optional)
Save Destination	Character	200	Input	This parameter specifies the save destination for the receive file. (Optional)
Receive File Name	Character	200	Input	This parameter specifies the file name of the receive file. (Optional)
Transfer Type	Character	1	Input	This parameter specifies the transfer type. (Optional)
Transfer Priority	Binary	2	Input	This parameter specifies the transfer priority. (Optional)

Status Code

The following tables show the status codes. Note that the status codes that are output differ when you use the Send File API for instant transfer. For the codes that are output when you carry out instant transfer, refer to Table 7.4 .

Table 7.3 Status codes for the Send File API
Status Code	Description
0	Execution of the API was completed successfully.
1	The applicable file ID does not exist.
2	An I/O error occurred during the acquisition of a record from the Send Management Information.
3	The Transfer Group is not specified in the Send Management Information.
4	The Format Information is not specified for format transfer.
5	Failed to open the Send Control file (HULFT.QUEUE).
6	Failed to create the Send work file. The API sets the details in the Detail Code.
7	Registration in the Send Control file (HULFT.QUEUE) failed.
8	An I/O error occurred during the acquisition of a record from the Format Information.
9	The applicable Transfer Group Information does not exist.
10	An I/O error occurred during the acquisition of a record from the Transfer Group Information.
11	Failed to create the Send work file. The API sets the details in the Detail Code.
12	An error in exclusive control occurred for the Send file during clearing.
13	Failed to clear the Send file.
14	Failed to issue the Send File order.
16	The Multi Format Information is not set for the multi format transfer.
17	An I/O error occurred during the acquisition of a record from the Multi Format Information.
18	An error occurred during the expansion processing for the Multi Format Information.
19	Failed to execute the Pre-send Job.
20	When you transfer files to multiple hosts using the Direct Transfer, you cannot specify for the Send files to be cleared.
21	Failed to acquire the UNIT information specified in the Send Management Information.
22	Failed to delete the Send file.
23	Cannot acquire the attribute information for the Send file. The API sets the details in the Detail Code.
25	The Record Format of the Send file is not supported by HULFT.
26	The record length or the block size of the Send file is set to 0 bytes.
27	You cannot delete Partitioned Organization files or VSAM files.
28	You cannot clear Partitioned Organization files or VSAM files.
29	The specified Send file is a Partitioned Organization file. Specify also the member name of the file.
30	The Format Information is not registered.
31	The Multi Format Information is not registered.
34	The operating version is not supported.
38	If the Code Set for Transfer (CS4TRNSFR) in the System Environment Settings is 'UTF-8,' you cannot use sending-side conversion.
40	When you use direct transfer and sending with RDW, you cannot send files other than files with a variable length record format that are 32752 bytes or less in length.
41	You cannot issue the Send File request for instant transfer.
50	A user table cannot be specified for code conversion to UTF-8.
51	The record length exceeded 32750 bytes after code conversion to UTF-8.
54	A function that cannot be used with the version of HULFT at the communication destination is specified. A string whose length is 9 bytes or more is specified for the File ID.
68	Use of plus signs is not supported in relative generation numbers for generation files.

Table 7.4 Status codes for the Send File API when you carry out instant transfer
Status Code	Description
0	Execution of the API was completed successfully.
5	Failed to open the Send Control file (HULFT.QUEUE).
7	Output of the send control file failed.
14	Execution of the MODIFY command for the Send File request failed.
23	Cannot acquire the attribute information for the Send file.
24	The data set organization of the send file is a data set organization that is not supported by HULFT.
25	The data set format of the send file is a data set format that is not supported by HULFT.
26	The record length or the block size of the send file is set to 0 bytes.
29	A member name is not specified for the send file which is a partitioned file.
34	The operating version is not supported.
61	Loading of the internal program failed due to insufficient memory. If you cannot resolve the problem and you have already concluded the Technical Support Agreement, please contact your Technical Support Service representative.
62	The send control file does not exist.
63	Failed to release the send control file.
64	There is an error in the specifications set on the interface.
65	Reading of the send control file failed.
66	The available memory is insufficient to run this program.
68	Use of plus signs is not supported in relative generation numbers for generation files.
101	Failed to allocate the file specified for Send Control File to Issue Instant Transfer (INSTTRANSCMDQUE) in the System Environment Settings.
102	An error occurred in conversion of the receive file save destination to UTF-8. Refer to the chapter on the Instant Transfer Send File API in Operation Manual and check the specification of the save destination for the receive file. If you cannot resolve the problem and you have already concluded the Technical Support Agreement, please contact your Technical Support Service representative.
103	An error occurred in conversion of the receive file name to UTF-8. Refer to the chapter on the Instant Transfer Send File API in Operation Manual and check the specification of the receive file name. If you cannot resolve the problem and you have already concluded the Technical Support Agreement, please contact your Technical Support Service representative.

Detail Codes (only for Status Codes '6' and '11.' The codes are expressed in hexadecimal.)

Detail Code	Description
0001	The OBTAIN macro failed.
0002	The data set does not exist on the applicable volume.
0003	The data set does not exist in the catalog.
0008	The Send file does not exist on the applicable volume.
0009	The applicable member of the Send file does not exist.
C3F7	An error occurred in code conversion.
C5D9	An error occurred during access of the Send work file.
C7D4	An insufficient-space error occurred. Increase the region size.
D3D5	The length of the Send file does not match the value set in the Format Information.
D4C6	An error occurred during the multi format conversion processing.
D6D7	Failed to open the Send file.
E4E3	The user table for single-byte code conversion is not defined.
Others	An error occurred in the DYNALLOC macro. The detail code of this macro is set as a code.

Example of Use

Case where you use COBOL

Below is a sample program that executes the Send File, using the Send File API (XRSNDAP).

The sample programs have two member names in the HULFT JCL library, "SMPSNDAP" and "SMPHSAP".

In the case of instant transfer, use "SMPHSAP".

Data to be used (SMPSNDAP)

The file ID of the record of the Send Management Information:: FILEID

      * 
      * HULFT SEND FILE API SAMPLE 
      * 
       IDENTIFICATION     DIVISION. 
       PROGRAM-ID.        SMPSNDAP. 
       ENVIRONMENT        DIVISION. 
       DATA               DIVISION. 
       WORKING-STORAGE    SECTION. 
      * 
      * XRSNDAP PARAMETER AREA 
      * 
       01  XRSNDAP-PARM. 
           02 XRSNDAP-VER      PIC X(6). 
           02 XRSNDAP-FILEID   PIC X(50). 
           02 XRSNDAP-RTNCD    PIC 9(4)  COMP. 
           02 XRSNDAP-ERRCD    PIC 9(4)  COMP. 
      *------------------------------------------------* 
       PROCEDURE          DIVISION. 
      * 
      * XRSNDAP PARAMETER AREA INITIALIZATION 
      * 
           INITIALIZE XRSNDAP-PARM. 
      * 
      * ISSUE REQUEST FOR SEND FILE 
      * 
           MOVE 'V08L04'       TO XRSNDAP-VER. 
           MOVE 'FILEID'       TO XRSNDAP-FILEID. 
           CALL 'XRSNDAP' USING XRSNDAP-PARM. 
      * 
           STOP RUN.

Data to be used (SMPHSAP)

File Name of the send file:: SNDFILE
Host Name of the receiving-side host:: ZOS
Port No. of the receiving-side host:: 30000
Save Destination of the receive file:: HUL001
File Name of the receive file:: RCVFILE
Transfer Type:: T
Transfer Priority:: 50

      * 
      * HULFT INSTANT TRANSFER API SAMPLE 
      * 
       IDENTIFICATION     DIVISION. 
       PROGRAM-ID.        SMPHSAP. 
       ENVIRONMENT        DIVISION. 
       DATA               DIVISION. 
       WORKING-STORAGE    SECTION. 
      * 
      * XRSNDAP PARAMETER AREA 
      * 
       01  XRSNDAP-PARM. 
           02 XRSNDAP-VER      PIC X(6). 
           02 XRSNDAP-FILEID   PIC X(50). 
           02 XRSNDAP-RTNCD    PIC 9(4)  COMP. 
           02 XRSNDAP-ERRCD    PIC 9(4)  COMP. 
           02 XRSNDAP-FILE     PIC X(44). 
           02 XRSNDAP-HOST     PIC X(50). 
           02 XRSNDAP-PORT     PIC 9(5)  COMP. 
           02 XRSNDAP-RCVL     PIC X(200). 
           02 XRSNDAP-RCVF     PIC X(200). 
           02 XRSNDAP-MODE     PIC X(1). 
           02 XRSNDAP-P        PIC 9(3)  COMP. 
      *------------------------------------------------* 
       PROCEDURE          DIVISION. 
      * 
      * XRSNDAP PARAMETER AREA INITIALIZATION 
      * 
           INITIALIZE XRSNDAP-PARM. 
      * 
      * ISSUE REQUEST FOR INSTANT TRANSFER 
      * 
           MOVE 'V08L04'                        TO XRSNDAP-VER. 
           MOVE 'SNDFILE'                       TO XRSNDAP-FILE. 
           MOVE 'ZOS'                           TO XRSNDAP-HOST. 
           MOVE 30000                           TO XRSNDAP-PORT. 
           MOVE 'HUL001'                        TO XRSNDAP-RCVL. 
           MOVE 'RCVFILE'                       TO XRSNDAP-RCVF. 
           MOVE 'T'                             TO XRSNDAP-MODE. 
           MOVE 50                              TO XRSNDAP-P. 
           CALL 'XRSNDAP' USING XRSNDAP-PARM. 
           DISPLAY XRSNDAP-RTNCD. 
      * 
           STOP RUN.

Note

Incorporate the following DD statements into the JCL to be executed:

Example of JCL

//XRFILE   DD DSN=HULFT.FILE,DISP=SHR                                           
//XRHOST   DD DSN=HULFT.HOST,DISP=SHR                                           
//XRQUE    DD DSN=HULFT.QUEUE,DISP=SHR                                          
//XRSYSIN  DD DSN=HULFT.PARMLIB(HULPRM),DISP=SHR                                
[//XREXTLIB DD DSN=HULFT.LOAD,DISP=SHR]

DD Name	Value	Description
XRFILE	HULFT.FILE	Send and Receive Management File
XRHOST	HULFT.HOST	Host Information File
XRQUE	HULFT.QUEUE	Send Control File
XRSYSIN	HULFT.PARMLIB(HULPRM)	System Environment Settings File
XREXTLIB	HULFT.LOAD	HULFT load module library (*1)

If you specify conversion of custom character code on the host on the sending side using a custom character table, you must add a library to store the custom character table. For details on custom character tables, refer to Administration Manual.