Writing a DLL filter

A DLL filter can convert data to a different format. For example, a DLL filter can convert line data to text format or to PDF format. If a DLL filter changes the data format, the filter must indicate the new data format in the document-format job attribute. DLL filters must convert the data to the printer code page.

To assist you in writing a new DLL filter, IBM® provides the source code for the aopfiltr.so DLL filter in these files:
  • cfilter.h, a header file that contains declarations and interface descriptions. Do not change the contents of this file.
  • cfilter.c, the source code for the aopfiltr.so filter.
Both files are in directory /usr/lpp/Printsrv/samples. For more information about aopfiltr.so, see Filters provided with Infoprint Server.
To customize the aopfiltr.so filter:
  • Modify file cfilter.c as necessary, using the comments in the prologs of the file.
  • Link the filter as a dynamic link library (DLL), as described in the comments in file cfilter.c.
Rule: Use the z/OS® UNIX extattr command to set the a extended attribute for the filter. To use the extattr command, you must have at least read access to the BPX.FILEATTR.APF resource in the FACILITY class profile. For example: 
extattr +a filtername.dll
For a more secure environment, do not link the filter with the AC=1 attribute. When you omit AC=1, the exit runs APF-authorized only when an APF-authorized program, such as Infoprint Server, calls it.
Parent topic: Writing a filter program

Input to a DLL filter

A DLL filter has access to this information:

  • Filter options and operands.
  • Environment variables.
  • Input data in a document. Text and line-data documents are already converted to the printer code page.
  • Name of the printer code page that is used to convert the data.
  • Format of the data, as determined by Infoprint Server or as specified by the job submitter.
  • The LPD control file in a format that is defined by RFC 1179.
  • The type of carriage controls in the input file.
  • The name of the input file.
  • The name of the printer definition for the print request.
  • Job attributes. Job attributes can be specified either by the job submitter or in the printer definition. For a list of Infoprint Server job attributes, see z/OS Infoprint Server User's Guide.

Output from a DLL filter

A DLL filter can return this output to Infoprint Server:
  • Modified data.
  • Format of the data.
  • The type of carriage controls.
  • Job attributes. Infoprint Server uses job attributes when it allocates data sets on the JES spool. For example, if the filter specifies the copies or form-definition job attribute, Infoprint Server allocates the data set on the JES spool as if the COPIES or FORMDEF JCL parameter were specified. For a list of Infoprint Server job attributes and corresponding JCL parameters, see z/OS Infoprint Server User's Guide.
  • Printer code page. Text and line-data documents are converted to this code page before the data is passed as input to the filter.
  • Return code. If the return code indicates an error, Infoprint Server ends processing of the document.