FTP Client Application Interface (FCAI) control block

The user program written in Cobol, C, assembler, and PL/I and the FTP Client Application Programming Interface use the FCAI control block to describe an instance of use of the interface. The space for this control block is acquired by the user program.

Tip: REXX programs do not use an FCAI control block. For REXX programs, see FTP Client Application Interface (FCAI) stem variables.
Requirement: The FCAI control block must be aligned on at least a fullword boundary and be in primary storage.
Guideline: FCAI_Map can be altered to embed in a structure that generates multiple copies of the FCAI. If this is done, ensure that additional storage in FCAI_UserArea is acquired in fullword increments to preserve the alignment of each copy of the FCAI control block.
Table 1 is a layout of the control block. The Type column indicates the type of value that the field contains: text (all text fields must be in EBCDIC), binary, or undefined. This column also contains the following information:
  • (I) to indicate input from the user program. If the field is defined by values that appear in a table following Table 1, there is a reference to that table.
  • (O) to indicate output from the interface program. If the field is defined by values that appear in a table following Table 1, there is a reference to that table.
  • (R) to indicate a reserved field.
  • (U) to indicate user area.
The field names in this table are the names used for assembler and PL/I. All sections of this topic use this name syntax with the following exceptions: Other than these differences for C and COBOL, the field names in the supplied macros and samples for each language are similar.
Table 1. FCAI control block
Field name Length Offset Description Type
FCAI_Map 256 and higher 0 FCAI control block. various
FCAI_DefinedFields 76 0 Fields defined to the interface. various
FCAI_Eyecatcher 4 0 Eyecatcher= FCAI; this field is required. (I) text
FCAI_Size 2 4 Size of FCAI; this field is required and has a minimum value of 256. (I) binary
FCAI_Version 1 6 Version of FCAI; this field is required. (I - see Table 2) binary
FCAI_PollWait 1 7 POLL wait timer in seconds (see FCAI_PollWait: Specifying a wait time before POLL). (I) binary
FCAI_ReqTimer 1 8 Request timer in seconds or 0 for none (see FCAI_ReqTimer: Controlling requests that retrieve results from the created z/OS FTP client process). (I) binary
FCAI_TraceIt 1 9 Trace indicator for this request (see Using the FTP client API trace). (I - see Table 3) binary
FCAI_TraceID 3 10 ID used in a trace record. This value is used only when a request initiates the interface trace function and does not change thereafter. (I) text
FCAI_TraceCAPI 1 13 TRACECAPI value on FTP.DATA statement. (O - see Table 4) binary
FCAI_TraceStatus 1 14 Status of the trace (see FCAI_Status_TraceFailed and FCAI_TraceStatus: Reporting failures in the interface trace function). (O - see Table 5) binary
FCAI_TraceSClass 1 15 SYSOUT class for trace file. This value is used only when a request initiates the interface trace function and does not change thereafter. (I) text
FCAI_TraceName 8 16 ddname of the trace file. (O) text
FCAI_Token 4 24 Interface token (do not alter after INIT). (O) binary
FCAI_RequestID 4 28 Last request (for example, 'SCMD'). (O) text
FCAI_RCV 16 32 Request completion values (see Interpreting results from an interface request). (O) binary
FCAI_Result 1 32 Request result (the return code register also contains this value). (O - see Table 6) binary
FCAI_Status 1 33 Status code. (O - see Table 7) binary
FCAI_IE 1 34 Interface error. (O - see Table 8) binary
FCAI_CEC 1 35 Client error code (see FTP return codes in the z/OS Communications Server: IP User's Guide and Commands). (O) binary
FCAI_ReplyCode 2 36 Server reply code or 0 if no reply (see FTPD reply codes in z/OS Communications Server: IP and SNA Codes). (O) binary
FCAI_SCMD 1 38 Subcommand code (see FTP subcommand codesFTP subcommand codesin z/OS Communications Server: IP User's Guide and Commands). (O) binary
Reserved 1 39 Reserved. (R) undefined
FCAI_ReturnCode 4 40 Return code (see Table 5 and Table 8 for errors that have associated return code data). (O) binary
FCAI_ReasonCode 4 44 Reason code (see Table 5 and Table 8 for errors that have associated reason code data). (O) binary
Summary fields for output lines that are held in the interface buffer
FCAI_NumberLines 4 48 Number of output lines returned by the request. (O) binary
FCAI_LongestLine 4 52 Size of the longest line. (O) binary
FCAI_SizeAll 4 56 Size of all output lines. (O) binary
FCAI_SizeMessages 4 60 Size of all message lines. (O) binary
FCAI_SizeReplies 4 64 Size of all reply lines. (O) binary
FCAI_SizeList 4 68 Size of all list lines. (O) binary
FCAI_SizeTrace 4 72 Size of all trace lines. (O) binary
FCAI_PID 4 76 Process ID of FTP client. (O) binary
Reserved and user areas
FCAI_ReservedForInterface 176 80 Reserved. (R) undefined
FCAI_UserArea 0 to unlimited 256 Start of user area. It is not necessary to add the size of the user area to the value in FCAI_Size. (U) undefined
Table 2. FCAI_Version field value
Name Value Description
FCAI_Version_Number 1 Version number

For more information about the values found in Table 3, see Using the FTP client API trace.

Table 3. FCAI_TraceIt field value
Name Value Description
FCAI_TraceIt_No 0 Do not trace this request.
FCAI_TraceIt_Yes 1 Trace this request.
Table 4. FCAI_TraceCAPI field value
Name Value Description
FCAI_TraceCAPI_C 0 Trace according to FCAI_TraceIt.
FCAI_TraceCAPI_A 1 Trace all events.
FCAI_TraceCAPI_N 2 Trace no events.

For more information about the values found in Table 5, see FCAI_Status_TraceFailed and FCAI_TraceStatus: Reporting failures in the interface trace function.

Table 5. FCAI_TraceStatus field value
Name Value Description Additional information returned with FCAI_Status_TraceFailed
FCAI_TraceStatus_OK 0 Tracing OK or not started None
FCAI_TraceStatus_StorageErr 1 Failed to acquire or access storage FCAI_ReturnCode = GETMAIN return code
FCAI_TraceStatus_AllocErr 2 Allocation error FCAI_ReturnCode = S99ERROR value or 8; FCAI_ReasonCode = S99ERSN for SMS error, S99INFO otherwise
FCAI_TraceStatus_OpenErr 3 Open error FCAI_ReturnCode contains the OPEN return code or FCAI_ReasonCode contains the ABEND code
FCAI_TraceStatus_WriteErr 4 Write error FCAI_ReasonCode=ABEND code
FCAI_TraceStatus_CloseErr 5 Close error FCAI_ReturnCode contains the CLOSE return code or FCAI_ReasonCode contains the ABEND code
FCAI_TraceStatus_SysoutClassErr 6 FCAI_TraceSClass contains a Sysout output class that is not valid None

For more information about the values found in Table 6, see Interpreting results from an interface request.

Table 6. FCAI_Result field value
Name Value Description
FCAI_Result_OK 0 OK with no additional status.
FCAI_Result_Status 1 Status code returned in FCAI_Status.
FCAI_Result_IE 2 Interface error returned in FCAI_IE.
FCAI_Result_CEC 3 Client Error Code returned in FCAI_CEC.
FCAI_Result_NoMatch 4 GETL request has no matches.
FCAI_Result_UnusableFCAI 17 FCAI is not usable.
FCAI_Result_TaskMismatch 18 Task is not the same as INIT task.
FCAI_Result_CliProcessKill 32 TERM issued BPX1KIL to end the client process. This is informational.

For more information about the values found in Table 7, see Prompts from the client and Interpreting results from an interface request.

Table 7. FCAI_Status field values
Name Value Description Additional Information
FCAI_Status_InProgress 1 Subcommand is in-progress. This status is returned for an SCMD issued in no-wait mode or if FCAI_ReqTimer expires on an SCMD issued in wait mode, and on any subsequent POLL requests until the SCMD completes.
FCAI_Status_PromptPass 2 Request prompted for a PASS subcommand. The interface accepts only SCMD PASS or a GETL request until the prompt is satisfied or this instance of the interface is terminated.
FCAI_Status_Acct 3 Request prompted for an ACCT subcommand. The interface accepts only SCMD ACCT or a GETL request until the prompt is satisfied or this instance of the interface is terminated.
FCAI_Status_TraceFailed 200 The interface trace failed on this request and has been disabled. This status is added to any other status returned. See FCAI_Status_TraceFailed and FCAI_TraceStatus: Reporting failures in the interface trace function for more information.
Table 8. FCAI_IE field values
Name Value Description Additional Information
General interface errors
FCAI_IE_RequestMissing 1 Request ID is missing. Request ID parameter not passed to EZAFTPKS.
FCAI_IE_RequestUnknown 2 Unknown request. Request ID not INIT, TERM, POLL, GETL, or SCMD.
FCAI_IE_ParmMissing 3 Parameter missing. Required parameter not passed to EZAFTPKS.
FCAI_IE_ParmStorageErr 4 Storage error for a parameter. Parameter list points to inaccessible storage.
FCAI_IE_TooManyParameters 5 More parameters were passed than are defined for this request type. Failure to include VL on an assembler language call to EZAFTPKS is one cause.
FCAI_IE_ControlErr 6 Error altering an open file descriptor. FCAI_ReturnCode and FCAI_ReasonCode contain values set by BPX1FCT in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
FCAI_IE_InternalErr 7 Internal error in the interface. For example, allocated buffer not found in chain; see FCAI_IE_InternalErr: Unanticipated exceptional conditions in the interface.
FCAI_IE_LengthInvalid 8 Negative or zero length. For example, zero buffer length with GETL; see FCAI_IE_LengthInvalid: Improper lengths passed to the interface.
INIT errors
FCAI_IE_APIAlreadyInit 16 Interface already initialized. This FCAI was used on a prior INIT request.
FCAI_IE_InitParmTooBig 17 INIT parameter is too big. FTP start parms string exceeds 2393 bytes.
FCAI_IE_APILoadFailed 18 The load of the interface failed. FCAI_ReturnCode and FCAI_ReasonCode contain values set by the BLDL service.
FCAI_IE_NoTokenAddr 19 Token address is 0. This FCAI has not been initialized and the current request is not INIT.
FCAI_IE_BadTokenAddr 20 Bad token field. FCAI_Token is not valid.
FCAI_IE_GetWorkareaFailed 21 Error acquiring workarea. FCAI_ReturnCode contains the value returned by the GETMAIN service.
FCAI_IE_ReqTimerExpired 22 INIT timed out waiting for output from the client. See FCAI_ReqTimer: Controlling requests that retrieve results from the created z/OS FTP client process for more information.
FCAI_IE_TooManyInitParms 23 More than 30 separate tokens were passed in the start parameters. Tokens are defined as characters or punctuation surrounded by whitespace.
FCAI_IE_TooManyEnvVars 24 More than nine environment variables were passed on the INIT. Use _CEE_ENVFILE= hfs_filename to pass more than nine environment variables.
FCAI_IE_CreatePipeErr 26 Error creating pipe to the client. FCAI_ReturnCode and FCAI_ReasonCode contain values set by BPX1PIP in the z/OS UNIX System Services Programming: Assembler Callable Services Reference.
FCAI_IE_SpawnErr 27 Error spawning the client. FCAI_ReturnCode and FCAI_ReasonCode contain values set by BPX1SPN in the z/OS UNIX System Services Programming: Assembler Callable Services Reference.
SCMD errors
FCAI_IE_ScmdParmTooBig 32 SCMD subcommand string too long. SCMD subcommand parameter string must not exceed 2064 bytes.
FCAI_IE_UNKMode 33 Mode parameter value incorrect. Mode parameter value must be W or N.
FCAI_IE_PassPromptErr 34 The current SCMD request is in error because PASS is required. A prior request set FCAI_Status_PromptPass and the current SCMD is not PASS.
FCAI_IE_AcctPromptErr 35 The current SCMD request is in error because ACCT is required. A prior request set FCAI_Status_PromptAcct and the current SCMD is not ACCT.
FCAI_IE_AlreadyInProgress 37 The current SCMD request is in error because an SCMD is in-progress. A prior SCMD returned FCAI_Status_InProgress. Issue a POLL request to complete the prior SCMD.
FCAI_IE_CliProcessStopped 38 The current request is in error because the client process was stopped normally with a QUIT subcommand. Only GETL can be issued prior to TERM when the client has processed a QUIT subcommand; the current request is not GETL or TERM.
FCAI_IE_WriteErr 41 Error writing to the client. FCAI_ReturnCode and FCAI_ReasonCode contain values set by BPX1WRT in the z/OS UNIX System Services Programming: Assembler Callable Services Reference.
INIT, SCMD, and POLL errors
FCAI_IE_ReadErr 42 Error reading from the client. FCAI_ReturnCode and FCAI_ReasonCode contain values set by BPX1RED in the z/OS UNIX System Services Programming: Assembler Callable Services Reference.
FCAI_IE_CliProcessBroken 47 Client process broken; send a TERM request. A previous error was encountered when communicating with the client or the client has terminated unexpectedly. Only GETL or TERM are accepted when this occurs.
POLL errors
FCAI_IE_NotInProgress 48 A POLL request was issued when no subcommand was in-progress. Processing can continue normally with the next request.
GETL errors
FCAI_IE_UnknownOperation 64 GETL OPERATION parameter is not recognized. OPERATION must be FIND or COPY.
FCAI_IE_UnknownType 65 GETL TYPE parameter is not recognized. TYPE must be one of the following values:
  • M - client message
  • R - server reply
  • T - client trace
  • L - LIST/NLST output
  • A - any
FCAI_IE_UnknownSequence 66 GETL FIND SEQUENCE parameter is not recognized. Sequence must be one of the following values:
  • F - first
  • L - last
  • N - next
FCAI_IE_VectorStorageErr 67 The buffer described by the vector cannot be accessed. See the description of the VECTOR parameter in Parameter values that are set by the application.
FCAI_IE_BufferTooSmall 68 The buffer described by the vector is too small to hold the first line of returned output. See GETL for more information.
FCAI_IE_TraceIDTooBig 69 Length of traceID must be 0 - 3 characters. Set only by the FTP client API for REXX.
FCAI_IE_TraceSClassTooBig 70 Length of traceSClass value must be 0 - 3 characters. Set only by the FTP client API for REXX.
FCAI_IE_UnknownTraceIt 71 The traceIt value is not recognized. Set only by the FTP client API for REXX.
FCAI_IE_ReqTimerInvalid 72 The request timer value is not in the range 0 - 255. Set only by the FTP client API for REXX.
FCAI_IE_LinesParmTooBig 73 The GETL lines stem name is more than 200 characters in length. Set only by the FTP client API for REXX.
FCAI_IE_PollWaitInvalid 74 The pollWait value is not in the range 0 - 255. Set only by the FTP client API for REXX.
FCAI_FCAI_IE_NumTraceInvalid 75 The numTrace value is not in the range 1 - 1000000. Set only by the FTP client API for REXX.
FCAI_IE_FcaiMapParmTooBig 76 The FCAI stem name is more than 250 characters in length. Set only by the FTP client API for REXX.
FCAI_IE_EnvVarStorageErr 77 Unable to allocate storage for an environment variable. Set only by the FTP client API for REXX.
FCAI_IE_SysoutClassErr 78 FCAI_TraceSClass contains a Sysout output class that is not valid. Set only by the FTP client API for REXX.
Define the space for the FCAI by including the appropriate macro or source copy book in your program as follows:
  • EZAFTPKA - Assembler macro found in SEZACMAC
  • EZAFTPKC - COBOL copy book found in SEZANMAC
  • ftpcapi.h - C header file found in /usr/include/
  • EZAFTPKP - PL/I include deck found in SEZANMAC
Parent topic: FTP Client Application Programming Interface (API)