AFPRSC (AFP Resource) keyword in printer files

You use this record-level keyword to specify an Advanced Function Printing (AFP) resource or a non-AFP resource stored in the integrated file system.

The AFPRSC keyword cannot be used to specify fonts, overlays, page segments, form definitions, or page definitions.

The format of the keyword is:

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

AFPRSC ('resource-name' | &resource-name-field
   object-type | object-comp-id | &object-type-field
   position-down | &position-down-field
   position-across | &position-across-field
   [(*SIZE width | &width-field height | &height-field)]
   [(*ROTATION  rotation | &rotation-field-name)]
   [(*PATH 'path-to-use' | *NONE | *CWD | &path-to-use-field-name)]
   [(*MAPOPT mapping-option | &mapping-option-field-name)]
   [(*COLORPRF color-profile | color-profile-comp-id | &color-profile-field-name)]
   [(*SECRSC 'external-name' | &external-name-field
     secondary-resource-type | sec-resource-comp-id | &sec-resource-type-field-name
     'internal-name' | internal-name-hex-id | &internal-name-field
     'secondary-resource-path' | *NONE | *CWD |  &secondary-resource-path-field)])

Note: When you provide the resource-name, path-to-use, external-name, or secondary-resource-path as a literal value, the operating system assumes that it is specified in the coded character set identifier (CCSID) of the DDS source physical file. When you provide the resource-name, path-to-use, external-name, or secondary-resource-path as a program-to-system field, the operating system assumes that it is specified in the default job CCSID.

The resource-name is the name of the file in the integrated file system, including the file extension, if there is one. If the complete name is not specified, the resource will not be found. The maximum size of the quoted string is 250 bytes. The name cannot contain characters that can be interpreted as path name delimiters. To ensure portability across all AFP platforms, see the MO:DCA Reference (SC31-6802) book for a list of characters that are allowed in an external resource name.

The object-type describes the format of the data in the named file. Currently supported values are listed in the following table under the Object type name column. An object-comp-id value can be provided instead of the object-type. The corresponding object-comp-id values are listed in the following table under the Component ID column. The maximum size value allowed for an object-comp-id is 99999. The following table lists the currently supported object-types and the numeric value that identifies the type of the object:

Table 1. Object types supported on the AFPRSC keyword
Object type name	Component ID	Description
*JFIF	23	Commonly referred to as JPG
*PDFSPO	25	A PDF single-page object
*PDFSPOTR	49	A PDF single-page object with transparency
*PCLPO	34	A PCL page object
*BCOCA	– (see note)	An AFPDS BCOCA (bar code) object
*GOCA	– (see note)	An AFPDS GOCA (graphics) object
*IOCA	– (see note)	An AFPDS IOCA (image) object
*TIFF	14	Tag Image File Format
Note: The component ID for this object type is not used by the operating system.

If you specify an object component ID value that is not supported by the device, the result will be unpredictable and will depend on the device to which the file is sent.

The position-down parameter defines the vertical starting point of the resource relative to the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in).

The position-across parameter defines the horizontal starting point of the resource relative to the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in).

Note: The UOM parameter on the CRTPRTF command determines the units of measure for the position-down and position-across parameter values. If the value specified for a parameter is outside the valid range, it is flagged when the spooled file is created.

An error message is issued at print time if the resource does not fit on the page.

Use the optional width and height parameters to specify the size of the resource. They are specified as an expression of the form (*SIZE width height). If these parameters are omitted, then the size of the resource will not be changed (the resource will print with the size it was originally created with).

The optional width parameter defines the width of the resource. Valid values are 0.001 to 57.790 cm (0.001 to 22.750 in). If the width is specified, then the height parameter must also be specified.

The optional height parameter defines the height of the resource. Valid values are 0.001 to 57.790 cm (0.001 to 22.750 in). If the height is specified, then the width parameter must also be specified.

Note: The UOM parameter on the CRTPRTF command determines the units of measure for the width and height parameter values. If the value specified for a parameter is outside the valid range, it is flagged when the spooled file is created.

The optional rotation parameter allows you to specify a rotation value for the resource. Valid values are 0, 90, 180, and 270. It is specified as an expression of the form (*ROTATION rotation).

Consider the following additional points about the rotation parameter:

If the rotation parameter is omitted, then AFP or non-AFP resources are not automatically rotated when using the PAGRTT parameter on the printer file.
Verify that your printer supports this function.

Use the optional path-to-use parameter to further qualify the AFP resource. You should specify this parameter as an expression of the form (*PATH path-to-use). If you do not specify the path-to-use parameter, the environment variable QIBM_AFP_RESOURCES_PATH and the explicit path /QIBM/UserData/OS400/AFPresources are used to search for the file. You can specify these values for the path-to-use parameter:

*NONE. A path is not specified. *NONE has the same effect as if the path-to-use parameter is not supplied at all.
*CWD. The current working directory for the job is specified.
path-to-use. An absolute path name is specified. This must be a single directory. The value is a quoted string whose maximum length when the path name is provided in the DDS is 2000.

Note: When you reference a resource, if you specify (*PATH *NONE) or if you do not specify *PATH at all, the resource must be available through directories specified with the environment variable QIBM_AFP_RESOURCES_PATH or the explicit path /QIBM/UserData/OS400/AFPresources.

See How the operating system searches for resources on the path-to-use or the secondary-resource-path parameter for more information.

Use the optional mapping-option parameter to specify how the object should be mapped in the object placement area. It is specified as an expression of the form (*MAPOPT mapping-option).

The following table shows the available mapping options.

Mapping option	DDS value	Description
Position	*P	It specifies that the object is positioned at the upper left corner of the object placement area, as defined by the position-across and position-down parameters. Any portion of the object that falls outside the object placement area, as defined by the object's size, is not trimmed. If this occurs, the printer will report an error irrespective of the printer file's value for the FIDELITY parameter.
Position and trim	*PT	It specifies that the object is positioned at the upper left corner of the object placement area, as defined by the position-across and position-down parameters. Any portion of the object that falls outside the object placement area, as defined by the object's size, is trimmed.
Scale to fit	*ST	It specifies that the object is scaled to fit within the object placement area. The object is centered in the object placement area and it is scaled up or down to fit this area. Scaling is symmetrical. This option ensures that all of the data in the object is presented at the largest possible size and the object is not trimmed.
Center and trim	*CT	It specifies that the object is centered in the object placement area. Any portion of the object that falls outside the object placement area is trimmed.
Scale to fill	*SL	It specifies that the object is centered in the object placement area. The object is then scaled, so that it completely fills the object placement area. This might require that the object be asymmetrically scaled.

Not all options are available for all types of objects. The following table shows which options are available. If you do not specify a mapping option, the default mapping option for the object type is used.

Object type	Available mapping options
*BCOCA	*P (default)
*GOCA	PT (default), ST, CT, SL
*IOCA	PT (default), ST, CT, SL
All others	PT (default), P, ST, CT, *SL

Use the optional color-profile parameter to specify a color profile, if it is required by the object. It is specified as an expression of the form (*COLORPRF color-profile). The color profile is resident within a printer. A PostScript level 1 file might contain color that is specific to a geography-based offset press standard, which defines the color rendering.

Note: The color-profile parameter requires device support, and should be used only when you are certain that the intended device supports the color profile that you want to specify. Specifying a color profile that is not supported by a device can produce unpredictable results.

The following table lists the color profiles that are supported in AFP environments, and the numeric value that identifies the color profile. The currently supported values for color-profile are defined in the Color profile name column; the equivalent values for color-profile-comp-id are listed in the Component ID column. The maximum size value for a color-profile-comp-id is 99999.

Color profile name	Component ID	Description
*CMYKSWOP	0	CMYKSWOP (US)
*CMYKEURO	1	CMYK Euroscale (Europe)

If you specify an unsupported color-profile-comp-id value, the result will depend on the printer to which the file is sent. Some printers do not support a color profile with certain object types. If you specify any of these unsupported combinations, the result will depend on the printer to which the file is sent.

Use the optional secondary resource parameter to specify up to 5 secondary resources for the named resource. It is specified as an expression of the form (*SECRSC external-name secondary-resource-type internal-name secondary-resource-path). A secondary resource is a resource that resides in the integrated file system and is referenced within the file identified by the resource-name (also called the primary resource).

Note: Use of this optional parameter requires device support. Use this parameter when the resource identified in the resource-name parameter requires one or more secondary resources. Support for secondary resources is device dependent. This option should be used only when it is known that the resource identified in the resource-name field requires a secondary resource and that the necessary device support exists. Otherwise, unpredictable results might occur.

The external-name is the name of the file, including the file extension, if there is one. If the complete name is not specified, the secondary resource cannot be found. The value is a quoted string whose maximum size is 250 bytes. The name cannot contain characters that can be interpreted as path name delimiters.

The secondary-resource-type identifies the type of the secondary resource. The following table lists the corresponding secondary-resource-types and the numeric value that identifies the type of the secondary resource. Currently supported values for the secondary-resource-type are listed in the Resource type name column; the equivalent values for sec-resource-comp-id are listed under the Component ID column. The maximum size value for a sec-resource-comp-id is 99999.

Resource type name	Component ID	Description
*PDFRO	26	PDF resource object
*IOCAFS45RO	47	IOCA FS45 resource object

If you specify an unsupported sec-resource-comp-id value, the result depends on the device to which the file is sent. Some devices do not support secondary resources with certain object types. Also, some devices do not support any secondary resource or object type combination. If you specify any of these unsupported combinations, the result depends on the device to which the file is sent.

The internal-name is the name of the secondary resource as it is referenced in the primary resource. The value is a quoted string or a HEX string (internal-name-hex-id). This value might be different than the external-name. You must obtain the internal-name from the person or application that generated the primary resource. The maximum length of a quoted string is 250 bytes. The format of the internal-name-hex-id is X'hhhh' where 'h' are hexadecimal characters. The maximum number of HEX characters is 500. Therefore, the maximum length of a HEX string is 503 bytes.

You can specify a path indicating where the resource is stored with the secondary-resource-path. The possible values are listed as follows:

*NONE. A path is not specified.
*CWD. The current working directory for the job is specified.
Secondary-resource-path. An absolute path name is specified. This must be a single directory. The value is a quoted string whose maximum length when the path name is provided in the DDS is 2000.

Note: When referring to these resources, if you specify *NONE for the secondary resource path, the resource must be available through directories specified with environment variable QIBM_AFP_RESOURCES_PATH or the explicit path /QIBM/UserData/OS400/AFPresources.

See How the operating system searches for resources on the path-to-use or the secondary-resource-path parameter for more information.

You can specify the resource-name, object-type, position-down, position-across, width, height, rotation, path-to-use, mapping-option, color-profile, external-name, secondary-resource-type, internal-name, and secondary-resource-path parameters as constants, program-to-system fields, or a combination of both. For example, the required parameters can be expressed in the following ways:

AFPRSC('Some resource name'  *JFIF 10.2  11.2  ... )
AFPRSC(&field1 *JFIF 10.2  11.2   ... )
AFPRSC(&field1 &field2 10.2  11.2   ... )
AFPRSC(&field1 &field2 &field3 12.3   ... )
AFPRSC(&field1 *JFIF 10.3 &field3   ... )
AFPRSC(&field1 &field2 &field3 &field4  ... )

When you specify the resource-name as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined with a length in the range 1 to 250, data type A (character), and usage P (program-to-system).

When you specify the object-type as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined with a length of 10, data type A (character), and usage P (program-to-system). If you provide a numeric component ID for the value of the field, assign a zoned decimal value, left-aligned in the field, and padded with blanks or HEX zeros. The maximum size of the numeric component ID value is 99999.

When you specify position-down or position-across as program-to-system fields, the fields must exist in the same record format as the AFPRSC keyword. The fields must be defined as length 5 with 3 decimal positions, data type S, and usage P.

When you specify the width or height fields as program-to-system fields, the fields must exist in the same record format as the AFPRSC keyword. The fields must be defined as length 5 with 3 decimal positions, data type S, and usage P.

A program-to-system field for rotation must exist in the same record format as the AFPRSC keyword, and it must be defined as length 3 with 0 decimal positions, data type S, and usage P.

When you specify path-to-use as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined with a length in the range 1 to 5000, data type A (character), and usage P.

When you specify mapping-option as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined as length 3, data type A (character), and usage P.

When you specify color-profile as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined as length 9, data type A (character), and usage P. If you provide a numeric component ID for the value of the field, assign a zoned decimal value, left- aligned in the field, and padded with blanks or HEX zeros. The maximum size of the numeric component ID value is 99999.

When you specify external-name as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined with a length in the range of 1 to 250, data type A (character), and usage P.

When you specify secondary-resource-type as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined as length 11, data type A (character), and usage P. If you provide a numeric component ID for the value of the field, assign a zoned decimal value, left-aligned in the field and padded with blanks or HEX zeros. The maximum size of the numeric component ID value is 99999.

When you specify internal-name as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined with a length in the range of 3 to 252, data type A (character), and usage P. The first two bytes of the field's value must be a two byte binary length field. The value in the length field indicates the length of the name in the remainder of the program-to-system field.

When you specify secondary-resource-path as a program-to-system field, the field must exist in the same record format as the AFPRSC keyword. It must be defined with a length in the range of 1 to 5000, data type A (character), and usage P.

Specify DEVTYPE(*AFPDS) on the CRTPRTF command when AFPRSC is specified in the file. If DEVTYPE is changed to anything other than *AFPDS, the keyword is ignored and a warning message is issued at print time.

When the AFPRSC keyword is specified on a record format, all fields within the record format must be positioned using the POSITION keyword.

An error message is issued if a constant field is specified in a record format where the AFPRSC keyword is also specified.

Each resource-name can only be used to refer to a single AFP or non-AFP resource per page. Each external-name can be used only to refer to a single secondary resource per page. Multiple instances of the same resource are allowed on a page. Identical names that are specified with different paths are treated as different resources and will result in an error.

A maximum of 10 AFP or non-AFP resources can be used on a single page. Only one AFPRSC keyword can be used on a record.

AFP or non-AFP resources are not automatically rotated when using the PAGRTT keyword or the PAGRTT parameter on the printer file.

You cannot specify AFPRSC with the following keywords:

SPACEA
SPACEB
SKIPA
SKIPB

Option indicators are valid for this keyword.

How the operating system searches for resources on the path-to-use or the secondary-resource-path parameter

The operating system searches for resources for the path-to-use parameter or the secondary-resource-path parameter in the following way:

If you do not specify the path-to-use parameter for the primary resource path, or you specify (PATH *NONE), or if you specify *NONE for the secondary resource path:
1. If Print Services Facility (PSF) is being used, the following is done:
  - The paths specified with the system-level value for environment variable QIBM_AFP_RESOURCES_PATH are searched for Data Object Resource Access Tables that specify the resource for which the search is being conducted. Independent disk pools are not included in the Resource Access Table (RAT) search. Subdirectories are not searched for a Data Object RAT. If the resource is specified in the RAT and one or more Color Management Resources (CMR) are associated with the resource, PSF will search for the CMRs.
  - If a Data Object RAT is not found or does not specify the resource, the /QIBM/UserData/OS400/AFPresources directory on the system ASP is searched for a Data Object RAT. Subdirectories are not searched for a Data Object RAT. If the resource is specified in the RAT and one or more CMRs are associated with the resource, PSF will search for the CMRs.
2. The paths specified with the system-level value for environment variable QIBM_AFP_RESOURCES_PATH are searched, unless PSF is being used and the resource has been found.
3. If the resource is not found, and the spooled file resides on an independent disk pool, the /<independent-disk-pool-name>/QIBM/UserData/OS400/AFPresources directory, if it exists, is searched. You are responsible for creating directory /QIBM/UserData/OS400/AFPresources on an independent disk pool. Subdirectories are not searched.
4. If the resource is not found or the spooled file resides on *SYSBAS, the /QIBM/UserData/OS400/AFPresources directory on the system ASP is searched. Subdirectories are not searched.
If you specify (*PATH *CWD) for the primary resource path or *CWD for the secondary resource path:
1. The current working directory for the job that generated the spooled file is searched.
2. If the resource is not found, the paths specified with the system-level value for environment variable QIBM_AFP_RESOURCES_PATH are searched.
3. If the resource is not found and the spooled file resides on an independent disk pool, the /<independent-disk-pool-name>/QIBM/UserData/OS400/AFPresources directory, if it exists, is searched. You are responsible for creating directory /QIBM/UserData/OS400/AFPresources on an independent disk pool. Subdirectories are not searched.
4. If the resource is not found or the spooled file resides on *SYSBAS, the /QIBM/UserData/OS400/AFPresources directory on the system ASP is searched. Subdirectories are not searched.
5. If Print Services Facility (PSF) is being used and the resource has not been found then the following is done:
  - The paths specified with the system-level value for environment variable QIBM_AFP_RESOURCES_PATH are searched for Data Object Resource Access Tables (RAT) that specify the resource for which the search is being conducted. Independent disk pools are not included in the Data Object RAT search. If the resource is specified in the RAT and one or more CMRs are associated with the resource, PSF will search for the CMRs.
  - If a Data Object RAT is not found or does not specify the resource, the /QIBM/UserData/OS400/AFPresources directory on the system ASP is searched for a Data Object RAT. Subdirectories are not searched for a Data Object RAT. If the resource is specified in the RAT and one or more CMRs are associated with the resource, PSF will search for the CMRs.
If you specify a path name, the specified path, which must be absolute and a single directory, is searched. If the resource is not found, an error is reported. No further searching is performed.

When you specify a specific path name and send the spooled file to another IBM® i model, that path must exist on the receiving system. If the path does not exist on the receiving system, an error is reported when searching for the resource.

When you specify *CWD or a specific path and send the spooled file to a system other than one running IBM i, the path information will be ignored by the receiving system.

Example 1

The following example shows how to specify the AFPRSC keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A*
     A          R REC1                      AFPRSC('My_resource' *PDFSPO 1.234 +
     A                                      14.62)
     A*
     A          R REC2                      AFPRSC(&RESN &RESTYP &POSD &POSA)
     A            RESN         125A  P
     A            RESTYP        10A  P
     A            POSD           5S 3P
     A            POSA           5S 3P
     A*
     A          R REC3                      AFPRSC('Some_resource' *IOCA +
     A                                      4.332 5.661 (*SIZE 10.12 12.345) +  
     A                                      (*ROTATION 90) (*PATH *CWD))
     A          R REC4                      AFPRSC(&RESN &RESTYP &POSD &POSA +
     A                                      (*SIZE &WDTH &HGT) +
     A                                      (*ROTATION &ROT) (*PATH &PATH))
     A            RESN         125A  P
     A            RESTYP        10A  P
     A            POSD           5S 3P
     A            POSA           5S 3P	
     A            WDTH           5S 3P
     A            HGT            5S 3P
     A            ROT            3S 0P
     A            PATH         500A  P	
     A          R REC5                      
     A  10                                  AFPRSC('Optional_resource'  + 
     A                                      *PDFSPO +
     A                                      1.2 4.6 (*MAPOPT *P)(*COLORPRF +   
     A                                      *CMYKSWOP) +
     A                                      (*SECRSC 'My resource' 26 +
     A                                      'Internal name' '/My/path')			
     A

Note: The UOM parameter on the CRTPRTF command determines the units of measure for the parameter values for the size and positioning parameters.

REC1 prints resource 'My_resource' found in either the environment variable QIBM_AFP_RESOURCES_PATH or the explicit path /QIBM/UserData/OS400/AFPresources. The resource is a PDFSPO resource. The resource prints 1.234 units down and 14.62 units across from the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command.

REC2 allows the application program to specify the resource name, resource type, the position down and the position across parameters by setting program variables at run time. The resource name is provided in variable RESN. The object type of the resource is provided in RESTYP. The resource is positioned by the values in POSD (position down) and POSA (position across).

REC3 uses optional keyword parameters. The resource named 'Some_resource' prints 4.332 units down and 5.661 units across from the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. The resource is an IOCA object. It prints with a size of 10.12 units by 12.345 units. It is rotated 90 degrees and found in the user's current working directory.

REC4 uses program-to-system fields for all of the parameters for the keyword. Therefore, the values for the parameters are supplied at run time.

REC5 prints the resource named 'Optional resource' only if indicator 10 is on. REC5 also illustrates the use of additional optional parameters. The position mapping option is requested. A color profile of CMYKSWOP is requested. A secondary resource object 'My resource' whose secondary resource type is PDF resource object is provided; its internal name is 'Internal name' and it is found in path '/My/path'.

Example 2

The second example uses DDS and P-fields.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
      *
                R REC1                      AFPRSC(&RESN &OBJT &OFFD &OFFA)
      *
                RESN          10A  P
                OBJT          10A  P
                OFFD           5S 3P
                OFFA           5S 3P

The following example illustrates the location of the resource using the previous DDS code. The application program specifies the resource name and object type by setting fields RESN and OBJT. The application program also sets a value of 2 in field OFFD and a value of 2 in field OFFA. Both the FRONTMGN and BACKMGN parameters on the CRTPRTF command are set to 2.

An illustration of the results produced by Example 2.