Resource exit

The line-data transform provides an exit that enables you to filter (exclude) resources. This exit is useful in controlling resources at the file-name level. For example, assume you only wanted to use those fonts that are not shipped with InfoPrint Manager. You could code this exit program to contain a table of all fonts shipped with InfoPrint Manager and filter those from the resource file. Security is another consideration for using this exit because you could prevent certain named resources from being included. The program invoked at this exit is defined by the resexitkeyword of the line2afp command.

This exit receives control before a resource is read from a directory. The exit program can request that the resource be processed or ignored (skipped), but it cannot substitute another resource name in place of the requested one. If the exit requests that any overlay be ignored, the line-data transform automatically ignores any resources the overlay might have referenced (that is, fonts and page segments).

Sample resource exit C language header contains a sample C language header that describes the control block that is passed to the exit program.

/*********************************************************************/
/* RESEXIT STRUCTURE                                                 */
/*********************************************************************/
typedef struct _RESEXIT_PARMS /* Parameters for resource record exit */
{
   char           *work;      /* Address of 16-byte static work area */
   PFATTR         *pfattr;    /* Address of print file attribute info*/
   char           resname[8]; /* Name of requested resource (8 byte) */
   char           restype;    /* Type of resource                    */
   char           request;    /* Ignore or process the resource      */
   char           eof;        /* Last call indicator                 */
   unsigned short resnamel;   /* Length of resource name         @05A*/
   char           pad1[3];    /* padding byte                    @05A*/
   char           resnamf[250]; /* Rsrc name if more than 8 bytes@05A*/
} RESEXIT_PARMS;

The address of the control block containing these parameters is passed to the resource-record exit:

work (Bytes 1–4)

A pointer to a static, 16-byte memory block. The exit program can use this parameter to save information across calls (for example, pointers to work areas). The 16-byte work area is aligned on a full word boundary and is initialized to binary zeros before the first call. A user-written exit program must provide the code required to manage this work area.

pfattr (Bytes 5–8)

A pointer to the print file attribute data structure. See Attributes of the line-data input file for more information about the format of this data structure and the information presented.

resname (Bytes 9–16)

Specifies the name of the requested resource. The exit program cannot modify or change this value.

restype (Byte 17)

Specifies the type of resource the name refers to. This is a one-byte hexadecimal value where:

X'03'

Specifies a GOCA (graphics) object

X'05'

Specifies a BCOCA (barcode) object

X'06'

Specifies an IOCA (IO image) object

X'40'

Specifies a font character set

X'41'

Specifies a code page

X'FB'

Specifies a page segment

X'FC'

Specifies an overlay

The line-data transform does not call this exit for these resource types:

• Page definition

  The page definition (pagedef keyword) is a required resource for transforming a line-data file.

• Form definition

  The form definition (formdef keyword) is a required resource for printing a transformed line-data file.

• Coded fonts

  The line-data transform must process coded fonts to determine the names of the code pages and font character sets they reference. This is necessary in creating Map Coded Font-2 (MCF-2) structured fields.

request (Byte 18)

Specifies how the line-data transform processes the resource. On entry to the exit program, this parameter is X'00'. When the exit program returns control to the line-data transform, this parameter must have the value X'00' or X'01' where:

X'00'

Specifies that the line-data transform should process the resource.

X'01'

Specifies that the line-data transform should ignore the resource.

A value of X'00' on entry to the exit program specifies that the resource be processed. If you want to ignore the resource, change the request byte value to X'01'. Any value greater than X'01' is interpreted as X'00' and the resource is processed.

resnamel

Specifies the length of the meaningful characters in the resnamef field.

pad1

A padding byte to get the resnamef on a word boundary.

resnamef

The actual name of the resource if it is greater then 8 characters in length. If the name is 8 characters or less in length, the name is stored in the resname field instead.

eof (Byte 19)

An end-of-file (eof) indicator. This indicator is a one-byte character code that signals when the line-data transform has written the last record.

When eof is signaled (eof value = ‘Y’), the last record has already been presented to the resource exit. The pointer record is no longer valid. Records may not be inserted after eof is signaled. These are the only valid values for this parameter:

Y

Specifies that the last record has been written.

N

Specifies that the last record has not been written.

This end-of-file flag, used as a last-call indicator, returns control to the line-data transform. The exit program cannot change this parameter.