# ipptoolfile

## NAME



           ipptoolfile - ipptool file format
    


## DESCRIPTION



           The ipptool(1) program accepts free-form plain text files that
           describe one or more IPP requests.  Comments start with the "#"
           character and continue to the end of the line.  Each request is
           enclosed by curly braces, for example:
    
               # This is a comment
               {
                 # The name of the test
                 NAME "Print PDF File"
    
                 # The request to send
                 OPERATION Print-Job
    
                 GROUP operation-attributes-tag
                 ATTR charset attributes-charset utf-8
                 ATTR language attributes-natural-language en
                 ATTR uri printer-uri $uri
                 ATTR name requesting-user-name $user
                 ATTR mimeMediaType document-format application/pdf
    
                 GROUP job-attributes-tag
                 ATTR collection media-col {
                   # US Letter plain paper from the "main" tray
                   MEMBER collection media-size {
                     MEMBER integer x-dimension 21590
                     MEMBER integer y-dimension 27940
                   }
                   MEMBER integer media-top-margin 423
                   MEMBER integer media-bottom-margin 423
                   MEMBER integer media-left-margin 423
                   MEMBER integer media-right-margin 423
                   MEMBER keyword media-source "main"
                   MEMBER keyword media-type "stationery"
                 }
    
                 FILE testfile.pdf
    
                 # The response to expect
                 STATUS successful-ok
                 EXPECT job-id OF-TYPE integer WITH-VALUE >0
                 EXPECT job-uri OF-TYPE uri
               }
               {
                 # The name of the test
                 NAME "Wait for Job to Complete"
    
                 # The request to send
                 OPERATION Get-Job-Attributes
    
                 GROUP operation-attributes-tag
                 ATTR charset attributes-charset utf-8
                 ATTR language attributes-natural-language en
                 ATTR uri printer-uri $uri
                 ATTR integer job-id $job-id
                 ATTR name requesting-user-name $user
    
                 # The response to expect
                 STATUS successful-ok
                 EXPECT job-id OF-TYPE integer WITH-VALUE $job-id
                 EXPECT job-uri OF-TYPE uri
                 EXPECT job-state OF-TYPE enum WITH-VALUE >5 REPEAT-NO-MATCH
                 EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
    
                 # Show the job state until completed...
                 DISPLAY job-state
                 DISPLAY job-state-reasons
               }
    
       **TOP-LEVEL DIRECTIVES**
           The following directives can be used outside of a _test_ :
    
           **{**_test_ **}**
                Defines a test.
    
           **DEFINE** _variable-name value_
                Defines the named variable to the given value. This is
                equivalent to specifying _-d variable-name=value_ on the
                **ipptool**(8) command-line.
    
           **DEFINE-DEFAULT** _variable-name value_
                Defines the named variable to the given value if it does not
                already have a value.
    
           **FILE-ID "**_identifier_**"**
                Specifies an identifier string for the current file.
    
           **IGNORE-ERRORS yes**
    
           **IGNORE-ERRORS no**
                Specifies whether, by default, **ipptool**(8) will ignore errors
                and continue with subsequent tests.
    
           **INCLUDE "**_filename_**"**
    
           **INCLUDE <**_filename_**>**
                Includes another test file. The first form includes a file
                relative to the current test file, while the second form
                includes a file from the **ipptool**(8) include directory.
    
           **INCLUDE-IF-DEFINED** _name_ **"**_filename_**"**
    
           **INCLUDE-IF-DEFINED** _name_ **<**_filename_**>**
                Includes another test file if the named variable is defined.
                The first form includes a file relative to the current test
                file, while the second form includes a file from the
                **ipptool**(8) include directory.
    
           **INCLUDE-IF-NOT-DEFINED** _name_ **"**_filename_**"**
    
           **INCLUDE-IF-NOT-DEFINED** _name_ **<**_filename_**>**
                Includes another test file if the named variable is not
                defined. The first form includes a file relative to the
                current test file, while the second form includes a file from
                the **ipptool**(8) include directory.
    
           **SKIP-IF-DEFINED** _variable-name_
    
           **SKIP-IF-NOT-DEFINED** _variable-name_
                Specifies that the remainder of the test file should be
                skipped when the variable is or is not defined.
    
           **STOP-AFTER-INCLUDE-ERROR no**
    
           **STOP-AFTER-INCLUDE-ERROR yes**
                Specifies whether tests will be stopped after an error in an
                included file.
    
           **TRANSFER auto**
                Specifies that tests will, by default, use "Transfer-
                Encoding: chunked" for requests with attached files and
                "Content-Length:" for requests without attached files.
    
           **TRANSFER chunked**
                Specifies that tests will, by default, use the HTTP/1.1
                "Transfer-Encoding: chunked" header. This is the default and
                is equivalent to specifying _-c_ on the **ipptool**(8) command-
                line. Support for chunked requests is required for
                conformance with all versions of IPP.
    
           **TRANSFER length**
                Specifies that tests will, by default, use the HTTP/1.0
                "Content-Length:" header. This is equivalent to specifying _-l_
                on the **ipptool**(8) command-line. Support for content length
                requests is required for conformance with all versions of
                IPP.
    
           **VERSION 1.0**
    
           **VERSION 1.1**
    
           **VERSION 2.0**
    
           **VERSION 2.1**
    
           **VERSION 2.2**
                Specifies the default IPP version number to use for the tests
                that follow.
    
       **TEST DIRECTIVES**
           The following directives are understood within a _test_ :
    
           **ATTR** _out-of-band-tag attribute-name_
    
           **ATTR** _tag attribute-name value[,...,value]_
    
           **ATTR** _tag attribute-name "value"[,...,"value"]_
    
           **ATTR** _tag attribute-name <hex-value>[,...,<hex-value>]_
                Adds an attribute to the test request.  Out-of-band tags
                (admin-define, delete-attribute, no-value, not-settable,
                unknown, unsupported) have no value.  Values for other tags
                are delimited by the comma (",") character - escape commas
                using the "\" character.  Common attributes and values are
                listed in the IANA IPP registry - see references below.
    
           **ATTR collection** _attribute-name_ **{ MEMBER** _tag member-name value(s)_
           _..._ **}**[ _..._ **,{**_..._ **}**]
                Adds a collection attribute to the test request.  Member
                attributes follow the same syntax as regular attributes and
                can themselves be nested collections.  Multiple collection
                values can be supplied as needed, separated by commas.
    
           **COMPRESSION deflate**
    
           **COMPRESSION gzip**
    
           **COMPRESSION none**
                Uses the specified compression on the document data following
                the attributes in a Print-Job or Send-Document request.
    
           **DELAY** _seconds_[_,repeat-seconds_]
                Specifies a delay in seconds before this test will be run.
                If two values are specified, the second value is used as the
                delay between repeated tests.
    
           **DISPLAY** _attribute-name_
                Specifies that value of the named attribute should be output
                as part of the test report.
    
           **EXPECT** _attribute-name_ [ _predicate(s)_ ]
    
           **EXPECT ?**_attribute-name predicate(s)_
    
           **EXPECT !**_attribute-name_
                Specifies that the response must/may/must not include the
                named attribute. Additional requirements can be added as
                predicates - see the "EXPECT PREDICATES" section for more
                information on predicates. Attribute names can specify member
                attributes by separating the attribute and member names with
                the forward slash, for example
                "media-col/media-size/x-dimension".
    
           **EXPECT-ALL** _attribute-name_ [ _predicate(s)_ ]
    
           **EXPECT-ALL ?**_attribute-name predicate(s)_
                Specifies that the response must/may include the named
                attribute and that all occurrences of that attribute must
                match the given predicates.
    
           **FILE filename**
                Specifies a file to include at the end of the request. This
                is typically used when sending a test print file.
    
           **GENERATE-FILE {**_parameters_ **}**
                Specifies that **ipptool** should generate PWG or Apple raster
                data for the printer.  See the "GENERATE-FILE PARAMETERS"
                section for information on the parameters you can specify.
    
           **GROUP tag**
                Specifies the group tag for subsequent attributes in the
                request.
    
           **IGNORE-ERRORS yes**
    
           **IGNORE-ERRORS no**
                Specifies whether **ipptool**(8) will ignore errors and continue
                with subsequent tests.
    
           **MONITOR-PRINTER-STATE**[ _printer-uri_ ] **{ EXPECT** _attribute-name_ [
           _predicate(s)_ ] **}**
                Specifies printer state monitoring tests to run in parallel
                with the test operation.  The monitoring tests will run until
                all of the **EXPECT** conditions are satisfied or the primary
                test operation has completed, whichever occurs first.
    
           **NAME "**_literal string_**"**
                Specifies the human-readable name of the test.
    
           **OPERATION** _operation-code_
                Specifies the operation to be performed.
    
           **PASS-IF-DEFINED** _variable-name_
    
           **PASS-IF-NOT-DEFINED** _variable-name_
                Specifies that the current test should be passed
                automatically when the variable is or is not defined.
    
           **PAUSE "**_message_**"**
                Displays the provided message and waits for the user to press
                a key to continue.
    
           **REQUEST-ID** _number_
    
           **REQUEST-ID random**
                Specifies the request-id value to use in the request, either
                an integer or the word "random" to use a randomly generated
                value (the default).
    
           **RESOURCE** _path_
                Specifies an alternate resource path that is used for the
                HTTP POST request. The default is the resource from the URI
                provided to the **ipptool**(8) program.
    
           **SKIP-IF-DEFINED** _variable-name_
    
           **SKIP-IF-NOT-DEFINED** _variable-name_
                Specifies that the current test should be skipped when the
                variable is or is not defined.
    
           **SKIP-PREVIOUS-ERROR yes**
    
           **SKIP-PREVIOUS-ERROR no**
                Specifies whether **ipptool**(8) will skip the current test if
                the previous test resulted in an error/failure.
    
           **STATUS** _status-code_ [ _predicate_ ]
                Specifies an expected response status-code value. Additional
                requirements can be added as predicates - see the "STATUS
                PREDICATES" section for more information on predicates.
    
           **TEST-ID "**_identifier_ "
                Specifies an identifier string for the current test.
    
           **TRANSFER auto**
                Specifies that this test will use "Transfer-Encoding:
                chunked" if it has an attached file or "Content-Length:"
                otherwise.
    
           **TRANSFER chunked**
                Specifies that this test will use the HTTP/1.1 "Transfer-
                Encoding: chunked" header.
    
           **TRANSFER length**
                Specifies that this test will use the HTTP/1.0 "Content-
                Length:" header.
    
           **VERSION 1.0**
    
           **VERSION 1.1**
    
           **VERSION 2.0**
    
           **VERSION 2.1**
    
           **VERSION 2.2**
                Specifies the IPP version number to use for this test.
    
       **EXPECT PREDICATES**
           The following predicates are understood following the **EXPECT** test
           directive:
    
           **COUNT** _number_
                Requires the **EXPECT** attribute to have the specified number of
                values.
    
           **DEFINE-MATCH** _variable-name_
                Defines the variable to "1" when the **EXPECT** condition
                matches.  A side-effect of this predicate is that this **EXPECT**
                will never fail a test.
    
           **DEFINE-NO-MATCH** _variable-name_
                Defines the variable to "1" when the **EXPECT** condition does
                not match.  A side-effect of this predicate is that this
                **EXPECT** will never fail a test.
    
           **DEFINE-VALUE** _variable-name_
                Defines the variable to the value of the attribute when the
                **EXPECT** condition matches.  A side-effect of this predicate is
                that this **EXPECT** will never fail a test.
    
           **DISPLAY-MATCH** _"message"_
                Displays the specified message when the **EXPECT** condition
                matches.
    
           **IF-DEFINED** _variable-name_
                Makes the **EXPECT** conditions apply only if the specified
                variable is defined.
    
           **IF-NOT-DEFINED** _variable-name_
                Makes the **EXPECT** conditions apply only if the specified
                variable is not defined.
    
           **IN-GROUP** _tag_
                Requires the **EXPECT** attribute to be in the specified group
                tag.
    
           **OF-TYPE** _tag[(limits)|tag|...]_
                Requires the **EXPECT** attribute to use one of the specified
                value tag(s).  Most value tags also support the specification
                of limits in parenthesis, for example "name(42)" would allow
                nameWith/WithoutLanguage strings up to 42 octets in length,
                "name(4:MAX)" would allow nameWith/WithoutLanguage strings
                between 4 and 255 octets in length, and "integer(-273:MAX)"
                would allow integers between -273 and 2147483647.
    
           **REPEAT-LIMIT** _number_
                Specifies the maximum number of times to repeat if the
                **REPEAT-MATCH** or **REPEAT-NO-MATCH** predicate is specified. The
                default value is 1000.
    
           **REPEAT-MATCH**
    
           **REPEAT-NO-MATCH**
                Specifies that the current test should be repeated when the
                **EXPECT** condition matches or does not match.
    
           **SAME-COUNT-AS** _attribute-name_
                Requires the **EXPECT** attribute to have the same number of
                values as the specified parallel attribute.
    
           **SAVE-CONTENT** _filespec_
    
           **SAVE-ALL-CONTENT** _filespec_
                Saves all "http" or "https" URI values to the specified
                location.  The filespec value is a filename or directory path
                and can contain the special strings "%basename%" to insert
                the base filename from the URI, "%ext%" to insert the
                extension from the URI, and "%index%" to insert the value
                number starting at 1.
    
           **WITH-ALL-CONTENT available**
    
           **WITH-CONTENT available**
                Requires that all URI values be accessible.  A "http" or
                "https" URI must respond to a GET request while a "ipp" or
                "ipps" URI must respond to a HEAD request.
    
           **WITH-ALL-CONTENT valid**
    
           **WITH-CONTENT valid**
                Requires that all "http" and "https" URI values be accessible
                and provide valid content.  Currently **ipptool** is able to
                validate CSS, HTML, ICC, IPP, JPEG, PDF, PNG, and Apple
                .strings files.
    
           **WITH-ALL-CONTENT valid-icon**
    
           **WITH-CONTENT valid-icon**
                Requires that all "http" and "https" URI values be accessible
                and provide valid PNG images for icons - 48x48, 128x128, or
                512x512 in size with transparency.
    
           **WITH-ALL-HOSTNAMES "**_literal string_**"**
    
           **WITH-ALL-HOSTNAMES "/**_regular expression_**/"**
                Requires that all URI values contain a matching hostname.
    
           **WITH-ALL-MIME-TYPES** _mime/type[,...,mime/type]_
    
           **WITH-MIME-TYPES** _mime/type[,...,mime/type]_
                Requires that all URI values provide one of the listed MIME
                media types.  For non-content tests, the target Printer must
                respond to HTTP HEAD requests with the MIME media type that
                would be returned by a GET or POST requests.  For "http" and
                "https" content tests, **ipptool** sends a HTTP GET request.  For
                "ipp" and "ipps" content tests, **ipptool** sends an IPP Get-
                Printer-Attributes request.
    
           **WITH-ALL-RESOURCES "**_literal string_**"**
    
           **WITH-ALL-RESOURCES "/**_regular expression_**/"**
                Requires that all URI values contain a matching resource
                (including leading /).
    
           **WITH-ALL-SCHEMES "**_literal string_**"**
    
           **WITH-ALL-SCHEMES "/**_regular expression_**/"**
                Requires that all URI values contain a matching scheme.
    
           **WITH-ALL-VALUES "**_literal string_**"**
                Requires that all values of the **EXPECT** attribute match the
                literal string. Comparisons are case-sensitive.
    
           **WITH-ALL-VALUES <**_number_
    
           **WITH-ALL-VALUES =**_number_
    
           **WITH-ALL-VALUES >**_number_
    
           **WITH-ALL-VALUES** _number_[_,...,number_]
                Requires that all values of the **EXPECT** attribute match the
                number(s) or numeric comparison. When comparing
                rangeOfInteger values, the "<" and ">" operators only check
                the upper bound of the range.
    
           **WITH-ALL-VALUES "false"**
    
           **WITH-ALL-VALUES "true"**
                Requires that all values of the **EXPECT** attribute match the
                boolean value given.
    
           **WITH-ALL-VALUES "/**_regular expression_**/"**
                Requires that all values of the **EXPECT** attribute match the
                regular expression, which must conform to the POSIX regular
                expression syntax.  Comparisons are case-sensitive.
    
           **WITH-ALL-VALUES-FROM** _attribute-name_
                Requires that all value(s) of the **EXPECT** attribute matches
                the value(s) in the specified attribute.  For example,
                "EXPECT-ALL media-col-database/media-source
                WITH-ALL-VALUES-FROM media-source-supported" requires that
                all the "media-source" values are listed as a value of the
                "media-source-supported" attribute.
    
           **WITH-DISTINCT-VALUES**
                Requires that all values of the **EXPECT** attribute are unique.
                Comparisons are case-sensitive.  Only charset, collection,
                enum, integer, keyword, mimeMediaType, naturalLanguage,
                rangeOfInteger, resolution, uriScheme attributes support this
                predicate.
    
           **WITH-HOSTNAME "**_literal string_**"**
    
           **WITH-HOSTNAME "/**_regular expression_**/"**
                Requires that at least one URI value contains a matching
                hostname.
    
           **WITH-RESOURCE "**_literal string_**"**
    
           **WITH-RESOURCE "/**_regular expression_**/"**
                Requires that at least one URI value contains a matching
                resource (including leading /).
    
           **WITH-SCHEME "**_literal string_**"**
    
           **WITH-SCHEME "/**_regular expression_**/"**
                Requires that at least one URI value contains a matching
                scheme.
    
           **WITH-VALUE "**_literal string_**"**
                Requires that at least one value of the **EXPECT** attribute
                matches the literal string. Comparisons are case-sensitive.
    
           **WITH-VALUE <**_number_
    
           **WITH-VALUE =**_number_
    
           **WITH-VALUE >**_number_
    
           **WITH-VALUE** _number_[_,...,number_]
                Requires that at least one value of the **EXPECT** attribute
                matches the number(s) or numeric comparison. When comparing
                rangeOfInteger values, the "<" and ">" operators only check
                the upper bound of the range.
    
           **WITH-VALUE "false"**
    
           **WITH-VALUE "true"**
                Requires that at least one value of the **EXPECT** attribute
                matches the boolean value given.
    
           **WITH-VALUE "/**_regular expression_**/"**
                Requires that at least one value of the **EXPECT** attribute
                matches the regular expression, which must conform to the
                POSIX regular expression syntax. Comparisons are case-
                sensitive.
    
           **WITH-VALUE-FROM** _attribute-name_
                Requires that the value(s) of the **EXPECT** attribute matches
                the value(s) in the specified attribute.  For example,
                "EXPECT job-sheets WITH-VALUE-FROM job-sheets-supported"
                requires that the "job-sheets" value is listed as a value of
                the "job-sheets-supported" attribute.
    
       **STATUS PREDICATES**
           The following predicates are understood following the **STATUS** test
           directive:
    
           **DEFINE-MATCH** _variable-name_
                Defines the variable to "1" when the **STATUS** matches. A side-
                effect of this predicate is that this **STATUS** will never fail
                a test.
    
           **DEFINE-NO-MATCH** _variable-name_
                Defines the variable to "1" when the **STATUS** does not match. A
                side-effect of this predicate is that this **STATUS** will never
                fail a test.
    
           **IF-DEFINED** _variable-name_
                Makes the **STATUS** apply only if the specified variable is
                defined.
    
           **IF-NOT-DEFINED** _variable-name_
                Makes the **STATUS** apply only if the specified variable is not
                defined.
    
           **REPEAT-LIMIT** _number_
                Specifies the maximum number of times to repeat. The default
                value is 1000.
    
           **REPEAT-MATCH**
    
           **REPEAT-NO-MATCH**
                Specifies that the current test should be repeated when the
                response status-code matches or does not match the value
                specified by the STATUS directive.
    
       **OPERATION CODES**
           Operation codes correspond to the hexadecimal numbers (0xHHHH) and
           names from RFC 8011 and other IPP extension specifications. Here
           is a complete list of names supported by **ipptool**(8):
    
               Acknowledge-Document
               Acknowledge-Identify-Printer
               Acknowledge-Job
               Activate-Printer
               Add-Document-Images
               Allocate-Printer-Resources
               Cancel-Current-Job
               Cancel-Job
               Cancel-Jobs
               Cancel-My-Jobs
               Cancel-Resource
               Cancel-Subscription
               Close-Job
               Create-Job
               Create-Job-Subscriptions
               Create-Printer
               Create-Printer-Subscriptions
               Create-Resource
               Create-Resource-Subscriptions
               Create-System-Subscriptions
               CUPS-Accept-Jobs
               CUPS-Accept-Jobs
               CUPS-Add-Modify-Class
               CUPS-Add-Modify-Printer
               CUPS-Authenticate-Job
               CUPS-Create-Local-Printer
               CUPS-Delete-Class
               CUPS-Delete-Printer
               CUPS-Get-Classes
               CUPS-Get-Default
               CUPS-Get-Devices
               CUPS-Get-Document
               CUPS-Get-PPD
               CUPS-Get-PPDs
               CUPS-Get-Printers
               CUPS-Move-Job
               CUPS-Reject-Jobs
               CUPS-Set-Default
               Deactivate-Printer
               Deallocate-Printer-Resources
               Delete-Printer
               Deregister-Output-Device
               Disable-All-Printers
               Disable-Printer
               Enable-All-Printers
               Enable-Printer
               Fetch-Document
               Fetch-Job
               Get-Job-Attributes
               Get-Jobs
               Get-Next-Document-Data
               Get-Notifications
               Get-Output-Device-Attributes
               Get-Printer-Attributes
               Get-Printer-Support-Files
               Get-Printer-Supported-Values
               Get-Printers
               Get-Subscription-Attributes
               Get-Subscriptions
               Get-System-Attributes
               Get-System-Supported-Values
               Hold-Job
               Hold-New-Jobs
               Identify-Printer
               Install-Resource
               Pause-All-Printers
               Pause-All-Printers-After-Current-Job
               Pause-Printer
               Pause-Printer-After-Current-Job
               Print-Job
               Print-URI
               Promote-Job
               Purge-Jobs
               Register-Output-Device
               Release-Held-New-Jobs
               Release-Job
               Renew-Subscription
               Reprocess-Job
               Restart-Job
               Restart-Printer
               Restart-System
               Resubmit-Job
               Resume-All-Printers
               Resume-Job
               Resume-Printer
               Schedule-Job-After
               Send-Document
               Send-Hardcopy-Document
               Send-Notifications
               Send-Resource-Data
               Send-URI
               Set-Job-Attributes
               Set-Printer-Attributes
               Set-Resource-Attributes
               Set-System-Attributes
               Shutdown-All-Printers
               Shutdown-One-Printer
               Shutdown-Printer
               Startup-All-Printers
               Startup-One-Printer
               Startup-Printer
               Suspend-Current-Job
               Update-Active-Jobs
               Update-Document-Status
               Update-Job-Status
               Update-Output-Device-Attributes
               Validate-Document
               Validate-Job
    
       **STATUS CODES**
           Status codes correspond to the hexadecimal numbers (0xHHHH) and
           names from RFC 8011 and other IPP extension specifications. Here
           is a complete list of the names supported by **ipptool**(8):
    
               client-error-account-authorization-failed
               client-error-account-closed
               client-error-account-info-needed
               client-error-account-limit-reached
               client-error-attributes-not-settable
               client-error-attributes-or-values-not-supported
               client-error-bad-request
               client-error-charset-not-supported
               client-error-compression-error
               client-error-compression-not-supported
               client-error-conflicting-attributes
               client-error-document-access-error
               client-error-document-format-error
               client-error-document-format-not-supported
               client-error-document-password-error
               client-error-document-permission-error
               client-error-document-security-error
               client-error-document-unprintable-error
               client-error-forbidden
               client-error-gone
               client-error-ignored-all-notifications
               client-error-ignored-all-subscriptions
               client-error-not-authenticated
               client-error-not-authorized
               client-error-not-fetchable
               client-error-not-found
               client-error-not-possible
               client-error-print-support-file-not-found
               client-error-request-entity-too-large
               client-error-request-value-too-long
               client-error-timeout
               client-error-too-many-subscriptions
               client-error-uri-scheme-not-supported
               cups-error-account-authorization-failed
               cups-error-account-closed
               cups-error-account-info-needed
               cups-error-account-limit-reached
               cups-see-other
               redirection-other-site
               server-error-busy
               server-error-device-error
               server-error-internal-error
               server-error-job-canceled
               server-error-multiple-document-jobs-not-supported
               server-error-not-accepting-jobs
               server-error-operation-not-supported
               server-error-printer-is-deactivated
               server-error-service-unavailable
               server-error-temporary-error
               server-error-version-not-supported
               successful-ok
               successful-ok-but-cancel-subscription
               successful-ok-conflicting-attributes
               successful-ok-events-complete
               successful-ok-ignored-notifications
               successful-ok-ignored-or-substituted-attributes
               successful-ok-ignored-subscriptions
               successful-ok-too-many-events
    
       **TAGS**
           Value and group tags correspond to the names from RFC 8011 and
           other IPP extension specifications. Here are the group tags:
    
               document-attributes-tag
               event-notification-attributes-tag
               job | job-attributes-tag
               operation | operation-attributes-tag
               printer | printer-attributes-tag
               resource-attributes-tag
               subscription-attributes-tag
               system-attributes-tag
               unsupported-attributes-tag
    
           Here are the value tags:
    
               admin-define
               boolean
               charset
               collection | begCollection
               dateTime
               default
               delete-attribute
               enum
               integer
               keyword
               language | naturalLanguage
               mimetype | mimeMediaType
               name | nameWithLanguage | nameWithoutLanguage
               no-value
               not-settable
               octetString
               rangeOfInteger
               resolution
               text | textWithLanguage | textWithoutLanguage
               unknown
               unsupported
               uri
               uriScheme
    
       **VARIABLES**
           The **ipptool**(8) program maintains a list of variables that can be
           used in any literal string or attribute value by specifying
           "_$variable-name_ ". Aside from variables defined using the _-d_ option
           or **DEFINE** directive, the following pre-defined variables are
           available:
    
           **$$** Inserts a single "$" character.
    
           **$ENV[**_name_**]**
                Inserts the value of the named environment variable, or an
                empty string if the environment variable is not defined.
    
           **$basename**
                Inserts the base filename (without directory path) of the
                path provided to **ipptool**(8) with the _-f_ option.
    
           **$date-current**
                Inserts the current date and time using the ISO-8601 format
                ("yyyy-mm-ddThh:mm:ssZ").
    
           **$date-start**
                Inserts the starting date and time using the ISO-8601 format
                ("yyyy-mm-ddThh:mm:ssZ").
    
           **$filename**
                Inserts the filename provided to **ipptool**(8) with the _-f_
                option.
    
           **$filetype**
                Inserts the MIME media type for the filename provided to
                **ipptool**(8) with the _-f_ option.
    
           **$hostname**
                Inserts the hostname from the URI provided to **ipptool**(8).
    
           **$job-id**
                Inserts the last "job-id" attribute value returned in a test
                response or 0 if no "job-id" attribute has been seen.
    
           **$job-uri**
                Inserts the last "job-uri" attribute value returned in a test
                response or an empty string if no "job-uri" attribute has
                been seen.
    
           **$notify-subscription-id**
                Inserts the last "notify-subscription-id" attribute value
                returned in a test response or 0 if no
                "notify-subscription-id" attribute has been seen.
    
           **$port**
                Inserts the port number from the URI provided to **ipptool**(8).
    
           **$resource**
                Inserts the resource path from the URI provided to
                **ipptool**(8).
    
           **$scheme**
                Inserts the scheme from the URI provided to **ipptool**(8).
    
           **$uri** Inserts the URI provided to **ipptool**(8).
    
           **$uriuser**
                Inserts the username from the URI provided to **ipptool**(8), if
                any.
    
           **$user**
                Inserts the current user's login name.
    


## GENERATE-FILE PARAMETERS



           The **GENERATE-FILE** directive dynamically generates raster pages for
           the destination printer.  Each page consists of a black border and
           the text "TEST-PAGE ####" repeated in the interior in several
           shades of gray and colors.  The following parameters are
           supported:
    
           **COLORSPACE auto**
    
           **COLORSPACE bi-level**
    
           **COLORSPACE color**
    
           **COLORSPACE monochrome**
    
           **COLORSPACE** _colorspace_bits_
                Specifies the output color space and bit depth.  "auto"
                chooses an available combination with preference for full
                color, "bi-level" chooses a B&W (bitmap) color space, "color"
                chooses a full color combination, and "monochrome" chooses a
                grayscale combination.  Otherwise, the value must be one of
                the registered IPP "pwg-raster-document-type-supported"
                keywords.  _NOTE:_ The "device N" color spaces are not current
                supported.
    
           **FORMAT image/pwg-raster**
    
           **FORMAT image/urf**
                Specifies the raster format to use, either "image/pwg-raster"
                (PWG Raster) or "image/urf" (Apple Raster).  The default is
                "image/urf" if supported, "image/pwg-raster" otherwise.
    
           **MEDIA default**
    
           **MEDIA ready**
    
           **MEDIA** _media-size-name_
                Specifies the output media size.  "default" uses the
                printer's default media size while "ready" uses the first
                ready (loaded) media reported by the printer.  Other media
                size names must conform the PWG self-describing media size
                format.
    
           **NUM-COPIES** _copies_
                Specifies the number of copies to produce.  The default is 1
                copy.
    
           **NUM-PAGES** _pages_
                Specifies the number of pages to produce.  The default is 1
                page for single-sided output and 2 pages for double-sided
                output.
    
           **ORIENTATION landscape**
    
           **ORIENTATION portrait**
    
           **ORIENTATION reverse-landscape**
    
           **ORIENTATION reverse-portrait**
                Specifies the orientation of the output.  The default is
                "portrait".
    
           **RESOLUTION default**
    
           **RESOLUTION max**
    
           **RESOLUTION min**
    
           **RESOLUTION** _resolution_**dpcm**
    
           **RESOLUTION** _horzontal_**x** _vertical_**dpcm**
    
           **RESOLUTION** _resolution_**dpi**
    
           **RESOLUTION** _horizontal_**x** _vertical_**dpi**
                Specifies the output resolution using the printer's supported
                resolutions or as specified in dots per inch or dots per
                centimeter.  "default" uses the median resolution of the
                printer and is the default, "min" uses the lowest resolution
                of the printer, and "max" uses the highest resolution of the
                printer.
    
            **SIDES one-sided**
    
            **SIDES two-sided-long-edge**
    
            **SIDES two-sided-short-edge**
                Specifies whether to print on one or both sides of the media.
                The default is "two-sided-long-edge" for portrait output and
                "two-sided-short-edge" for landscape output when supported by
                the printer, otherwise "one-sided" is used.
    


## EXAMPLES



           Query the "foo-default" and "foo-supported" Printer Description
           attributes and validate that all of its values are 'bar', 'baz',
           or 'none':
           {
             NAME "Validate 'foo' Attribute"
             OPERATION Get-Printer-Attributes
             GROUP operation-attributes-tag
             ATTR charset attributes-charset utf-8
             ATTR language attributes-natural-language en
             ATTR uri printer-uri $uri
             ATTR keyword requested-attributes foo-default,foo-supported
             EXPECT foo-default OF-TYPE keyword IN-GROUP printer-attributes-tag
                 COUNT 1 WITH-VALUE "/^(bar|baz|none)$$/"
             EXPECT foo-supported OF-TYPE keyword IN-GROUP printer-attributes-tag
                 WITH-ALL-VALUES "/^(bar|baz|none)$$/"
           }
           Query the "media-col-ready" Printer Status attribute and validate
           that the collection values contain "media-size" and "media-source"
           member attributes:
           {
             NAME "Validate 'foo' Attribute"
             OPERATION Get-Printer-Attributes
             GROUP operation-attributes-tag
             ATTR charset attributes-charset utf-8
             ATTR language attributes-natural-language en
             ATTR uri printer-uri $uri
             ATTR keyword requested-attributes media-col-ready
             EXPECT media-col-ready OF-TYPE collection IN-GROUP printer-attributes-tag
             EXPECT-ALL media-col-ready/media-size OF-TYPE collection COUNT 1
             EXPECT-ALL media-col-ready/media-size/x-dimension OF-TYPE integer(1:MAX) COUNT 1
             EXPECT-ALL media-col-ready/media-size/y-dimension OF-TYPE integer(0:MAX) COUNT 1
             EXPECT-ALL media-col-ready/media-source OF-TYPE keyword|name COUNT 1
           }
    


* * *