The EZAFCREP user exit

The EZAFCREP user exit is called when the FTP client receives a single-line reply or one line of a multiple line reply over the control connection that is sent from the server. A user exit routine that you write for EZAFCREP can inspect the FTP server reply, or end the FTP client after the FTP client receives a certain line of the reply sent from the server.

The following table is the parameter list that is passed to the EZAFCREP user exit:

Table 1. Parameter list passed to the EZAFCREP user exit
+ Offset (decimal)	Value
0	Pointer to a binary fullword that contains the number of parameters that follow (4).
4	Pointer to the 8-byte TCP connection ID. This is a character field. The TCP connection ID parameter uniquely identifies a control connection, and will remain the same for all user exit calls that are associated with a specific control connection.
8	Pointer to a buffer that contains a 2-byte length field followed by the FTP server reply line. The first two bytes hold the length of FTP server reply line. The buffer is padded with NULLs.
12	Pointer to a 40-byte buffer containing the socket APPLDATA for the current control connection. For more information about APPLDATA, see FTP Client Application Programming Interface (API) in z/OS Communications Server: IP Programmer's Guide and Reference.
16	Pointer to a 71-byte buffer to return a message when the user exit routine ends the FTP client. The user exit can put text in this buffer to explain why it ends the FTP client. If the exit supplies text in this buffer, the FTP client displays this text as message EZZ1556I. This buffer is initialized to blanks before each call to the EZAFCREP user exit.

The EZAFCREP user exit can return the following return codes to the FTP client in register 15:

RC=0: The exit accepts the reply.
RC=12: The exit ends the FTP client address space.

It can also return a reason code to the FTP client in register 0 if the return code in register 15 is not 0.

Results

When the EZAFCREP user exit returns code 0, FTP continues processing the reply.
When the EZAFCREP user exit returns code 12,
- FTP logs the reason code in register 0 with message EZA1546I, but does not interpret the reason code. The exit routine determines what the reason codes means.
- If the exit routine places a message into the 71-byte buffer, the client displays it as message EZA1556I before message EZA1546I. The client always displays message EZA1556I.
- If the input to the EZAFCREP user exit was one line of a multiple line reply, FTP flushes the remaining lines of the reply from its receive buffer, but does not print them.
- The FTP client ignores the return code if the EZAFCREP user exit decides to end the FTP client for a reply to the QUIT command.
- The FTP client ignores the return code if the EZAFCREP user exit decides to end the FTP client for a reply with the reply code in the range 100 - 199.

Example

If the user exit EZAFCREP is active, it is called for each line of a reply as it is received, and FTP displays each line of reply as it is received. If the user exit ends the FTP client in the middle of a multiple line reply, the FTP client will flush all remaining lines of the reply but not print them. The user exit will not be called again for this instance of the FTP client.

Suppose two user exit routines EZAFCRE1 and EZAFCRE2 are both installed for user exit EZAFCREP. EZAFCRE1 ends the FTP client when it receives the reply '214 – A fully qualified directory name (specified in quotes or' from subcommand help server cwd, EZAFCRE2 accepts any FTP reply. Suppose the operator installs the two exit routines in this order: first EZAFCRE1, then EZAFCRE2.

help server cwd                                                                 
EZA1701I >>> HELP CWD                                                           
EZA1582I The foreign server has this help:                                      
214-CWD directory-name: changes the working directory to this directory-name    
214-by appending it to the present working directory name.                      
214-A fully qualified directory name (specified in quotes or                    
EZA1556I EZAFCREP message: EZAFCRE1 Cancelled the FTP client                    
EZA1546I User exit EZAFCREP module EZAFCRE1 ended the FTP client - exit reason c
ode x'00000001' (1)                                                                    
EZA1701I >>> QUIT                                                               
221 Quit command received. Goodbye.        

The log on the system console:
- 00.07.42  EZAFCRE1 - Input - Offset: +00 Value: 00000003                 
- 00.07.42  EZAFCRE1 - Input - Offset: +04 Value: 00000088                 
- 00.07.42  EZAFCRE1 - Input - Offset: +08 Value: 214-CWD directory-     
           - name: changes the working directory to this directory-name                      
- 00.07.42  EZAFCRE2 - Input - Offset: +00 Value: 00000003                 
- 00.07.42  EZAFCRE2 - Input - Offset: +04 Value: 00000088                 
- 00.07.42  EZAFCRE2 - Input - Offset: +08 Value: 214-CWD directory-     
- name: changes the working directory to this directory-name         
- 00.07.42  EZAFCRE1 - Input - Offset: +00 Value: 00000003                 
- 00.07.42  EZAFCRE1 - Input - Offset: +04 Value: 00000088                 
- 00.07.42  EZAFCRE1 - Input - Offset: +08 Value: 214-by appending it    
           - to the present working directory name.                                                  
- 00.07.42  EZAFCRE2 - Input - Offset: +00 Value: 00000003                 
- 00.07.42  EZAFCRE2 - Input - Offset: +04 Value: 00000088                 
- 00.07.42  EZAFCRE2 - Input - Offset: +08 Value: 214-by appending it    
- to the present working directory name.                                                  
- 00.07.42  EZAFCRE1 - Input - Offset: +00 Value: 00000003                 
- 00.07.42  EZAFCRE1 - Input - Offset: +04 Value: 00000088                 
- 00.07.42  EZAFCRE1 - Input - Offset: +08 Value: 214-A fully qualified  
-  directory name (specified in quotes or

In this example, the EZAFCRE1 user exit routine is called three times and the EZAFCRE2 user exit routine is called two times. If EZAFCRE1 ends the FTP client for a certain reply:

EZAFCRE2 will not be called again for this invocation of EZAFCREP.
EZAFCREP will not be called again for this FTP client.

The FTP client will flush remaining reply lines from command HELP CWD. The FTP client sends a QUIT command to the server.