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:

Sending requests to the FTP client API uses the COBOL syntax; the field names contain a dash (-) instead of an underscore (_).
FTP client API for C functions uses the C syntax; the field names are identical to assembler and PL/I, but the constant definitions are all in upper case.

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