Instrumentation facility communications area (IFCA)

A monitor program's instrumentation facility communication area (IFCA) is a communications area between the monitor program and IFI. The IFCA contains information about the success of the call in its return code and reason code fields. The IFCA is a required parameter on all IFI requests.

Begin program-specific programming interface information.

The monitor program is responsible for allocating storage for the IFCA and initializing it. The IFCA must be initialized to binary zeros and the eye catcher, 4-byte owner field, and length field must be set by the monitor program. Failure to properly initialize the IFCA results in denying any IFI requests.

The monitor program is also responsible for checking the IFCA return code and reason code fields to determine the status of the request.

The IFCA fields are described in the following table.

Table 1. Instrumentation facility communication area. The IFCA is mapped by assembler mapping macro DSNDIFCA.
Name	Hex offset	Data type	Description
IFCALEN	0	Hex, 2 bytes	Length of IFCA.
IFCAFLGS	2	Hex, 1 byte	Processing flags. IFCAGLBL, X'80' This bit is on if an IFI request is to be processed on all members of a data sharing group. IFCASYNC, X'40' This bit is on when IFI run commands synchronously, for commands that can be run synchronously or asynchronously IFCARA64, X'20' When this bit is on, the first 8 bytes of the return area contains a pointer to the real 64-bit above-the-bar return area, where all return information is placed. For IFCID 0306 requests, both return areas must be in common storage. The first 4 bytes of the above-the-bar area must contain the following 4-byte string: 'I306'
	3	Hex, 1 byte	Reserved.
IFCAID	4	Character, 4 bytes	Eye catcher for block, IFCA.
IFCAOWNR	8	Character, 4 bytes	Owner field, provided by the monitor program. This value is used to establish ownership of an OP`n` destination and to verify that a requester can obtain data from the OP`n` destination. This value is not the same as the owner ID of a plan.
IFCARC1	C	4-byte signed integer	Return code for the IFI call. Binary zero indicates a successful call. For information about other return codes, see X'E6......' codes. For a return code of 8 from a COMMAND request, the IFCAR0 and IFCAR15 values contain additional information.
IFCARC2	10	4-byte signed integer	Reason code for the IFI call. Binary zero indicates a successful call. For information about other reason codes, see X'E6......' codes.
IFCABM	14	4-byte signed integer	Number of bytes moved to the return area. A non-zero value in this field indicates information was returned from the call. Only complete records are moved to the monitor program area.
IFCABNM	18	4-byte signed integer	Number of bytes that did not fit in the return area and still remain in the buffer. Another READA request retrieves that data. Certain IFI requests return a known quantity of information. Other requests terminate when the return area is full.
	1C	4-byte signed integer	Reserved.
IFCARLC	20	4-byte signed integer	Indicates the number of records lost prior to a READA call. Records are lost when the OP buffer storage is exhausted before the contents of the buffer are transferred to the application program via an IFI READA request. Records that do not fit in the OP buffer are not written and are counted as records lost.
IFCAOPN	24	Character, 4 bytes	Destination name used on a READA request. This field identifies the buffer requested, and is required on a READA request. Your monitor program must set this field. The instrumentation facility fills in this field on START TRACE to an OP`n` destination from an monitor program. If your monitor program started multiple OP`n` destination traces, the first one is placed in this field. If your monitor program did not start an OP`n` destination trace, the field is not modified. The OPn destination and owner ID are used on subsequent READA calls to find the asynchronous buffer.
IFCAOPNL	28	2-byte signed integer	Length of the OPn destinations started. On any command entered by IFI, the value is set to X'0004'. If an OP`n` destination is started, the length is incremented to include all OP`n` destinations started.
	2A	2-byte signed integer	Reserved.
IFCAOPNR	2C	Character, 8 fields of 4 bytes each	Space to return 8 OP`n` destination values.
IFCATNOL	4C	2-byte signed integer	Length of the trace numbers plus 4. On any command entered by IFI the value is set to X'0004'. If a trace is started, the length is incremented to include all trace numbers started.
	4E	2-byte signed integer	Reserved.
IFCATNOR	50	Character, 8 fields of 2 bytes each.	Space to hold up to eight EBCDIC trace numbers that were started. The trace number is required if the MODIFY TRACE command is used on a subsequent call.
IFCADL	60	Hex, 2 bytes	Length of diagnostic information.
ICFADDF	62	Hex, 2 bytes	Diagnostic information level: X'8000' The diagnostic area is for Db2 11 or later.
IFCADD	64	Character, 80 bytes	Diagnostic information. IFCACR0, offset 64, 4 bytes For COMMAND requests, this field contains -1 or the return code from the component that executed the command. IFCACR15, offset 68, 4 bytes For COMMAND requests, the IFCACR15 field contains one of the following values: 0 The command completed successfully. 4 Internal error. 8 The command was not processed because of errors in the command. 12 The component that executed the command returned the return code in IFCAR0. 16 An abend occurred during command processing. Command processing might be incomplete, depending on when the error occurred. See IFCAR0 for more information. 20 Response buffer storage was not available. The command completed, but no response messages are available. See IFCAR0 for more information. 24 Storage was not available in the `ssnm`MSTR address space. The command was not processed. 28 CSA storage was not available. If a response buffer is available, the command might have partially completed. See IFCAR0 for more information. 32 The user is not authorized to issue the command. The command was not processed. IFCAR0, offset 6C, 4 bytes Log manager reason code for IFCID 0129 requests, if IFCARC2 is 00E60834, 00E60835, or 00E60836. IFCAR15, offset 70, 4 bytes Log manager return code for IFCID 0129 requests, if IFCARC2 is 00E60834, 00E60835, or 00E60836. IFCAR15 offset 70, 4 bytes IFCAGBPN, offset 74, 8 bytes This is the group buffer pool name in error if IFCARC2 is 00E60838 or 00E60860 IFCABSRQ, offset 88, 4 bytes If the reason code is 00E60863, and the IFI request is a READS request for a proxy data sharing group in a GDPS® Continuous Availability with zero data loss environment, this value is a diagnostic reason code. If the reason code is 00E60864, this value is the size of the return area that is required. IFCAHLRS, offset 8C, 10 bytes This field contains one of the following values: If WQALLMOD='H', the highest LRSN or log RBA in the active log. If WQALLMOD=L', the difference between the current and previous LRSN for the system IFCAFCI, offset 8C, 10 bytes If IFCARC2 is 00E60854 or 00E60834, this field overlays IFCAHLRS. It contains the address of the first CI in the active log.
IFCAGRSN	98	Four-byte signed integer	Reason code for the situation in which an IFI calls requests data from members of a data sharing group, and not all the data is returned from group members.
IFCAGBM	9C	Four-byte signed integer	Total length of data that was returned from other data sharing group members and fit in the return area.
IFCAGBNM	A0	Four-byte signed integer	Total length of data that was returned from other data sharing group members and did not fit in the return area.
IFCADMBR	A4	Character, 8 bytes	Name of a single data sharing group member on which an IFI request is to be executed. Otherwise, this field is blank. If this field contains a member name, Db2 ignores field IFCAGLBL.
IFCARMBR	AC	Character, 8 bytes	Name of the data sharing group member from which data is being returned. Db2 sets this field in each copy of the IFCA that it places in the return area, not in the IFCA of the application that makes the IFI request.

End program-specific programming interface information.