[thirdparty/cups.git] / doc / help / man-ipptoolfile.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Man Pages -->
<head>
	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	<title>ipptoolfile(5)</title>
</head>
<body>
<h1 class="title">ipptoolfile(5)</h1>
<h2 class="title"><a name="NAME">Name</a></h2>
ipptoolfile - ipptool file format

<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
The <a href='man-ipptool.html?TOPIC=Man+Pages'>ipptool(1)</a> 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 curley braces, for example:
<pre>

    # This is a comment
    {
      # The name of the test
      NAME "Print PostScript Job"

      # 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
      FILE testfile.ps

      # The response to expect
      STATUS successful-ok
      EXPECT attributes-charset OF-TYPE charset
      EXPECT attributes-natural-language OF-TYPE naturalLanguage
      EXPECT job-id OF-TYPE integer
      EXPECT job-uri OF-TYPE uri
    }
    {
      # The name of the test
      NAME "Get Attributes of PostScript Job"

      # 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 attributes-charset OF-TYPE charset
      EXPECT attributes-natural-language OF-TYPE naturalLanguage
      EXPECT job-id OF-TYPE integer
      EXPECT job-uri OF-TYPE uri
      EXPECT job-state OF-TYPE enum
      EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
    }
</pre>

<h2 class="title"><a name="TOP-LEVEL_DIRECTIVES">Top-level Directives</a></h2>
The following directives can be used outside of a test:
<dl>
<dt>{ test }
</dt>
<dd>Defines a test.
</dd>
<dt>DEFINE variable-name value
</dt>
<dd>Defines the named variable to the given value. This is equivalent to specifying
"-d variable-name=value" on the <i>ipptool</i> command-line.
</dd>
<dt>DEFINE-DEFAULT variable-name value
</dt>
<dd>Defines the named variable to the given value if it does not already have a
value.
</dd>
<dt>IGNORE-ERRORS yes
</dt>
<dd></dd>
<dt>IGNORE-ERRORS no
</dt>
<dd>Specifies whether, by default, <i>ipptool</i> will ignore errors and continue with
subsequent tests.
</dd>
<dt>INCLUDE "filename"
</dt>
<dd></dd>
<dt>INCLUDE &lt;filename>
</dt>
<dd>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 <i>ipptool</i>
include directory.
</dd>
<dt>INCLUDE-IF-DEFINED name "filename"
</dt>
<dd></dd>
<dt>INCLUDE-IF-DEFINED name &lt;filename>
</dt>
<dd>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 <i>ipptool</i> include directory.
</dd>
<dt>INCLUDE-IF-NOT-DEFINED name "filename"
</dt>
<dd></dd>
<dt>INCLUDE-IF-NOT-DEFINED name &lt;filename>
</dt>
<dd>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 <i>ipptool</i> include directory.
</dd>
<dt>SKIP-IF-DEFINED variable-name
</dt>
<dd></dd>
<dt>SKIP-IF-NOT-DEFINED variable-name
</dt>
<dd>Specifies that the remainder of the test file should be skipped when the
variable is or is not defined.
</dd>
<dt>TRANSFER auto
</dt>
<dd>Specifies that tests will, by default, use "Transfer-Encoding: chunked" for
requests with attached files and "Content-Length:" for requests without attached
files.
</dd>
<dt>TRANSFER chunked
</dt>
<dd>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
<i>ipptool</i> command-line. Support for chunked requests is required for
conformance with all versions of IPP.
</dd>
<dt>TRANSFER length
</dt>
<dd>Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:"
header. This is equivalent to specifying "-l" on the <i>ipptool</i> command-line.
Support for content length requests is required for conformance with all
versions of IPP.
</dd>
<dt>VERSION 1.0
</dt>
<dd></dd>
<dt>VERSION 1.1
</dt>
<dd></dd>
<dt>VERSION 2.0
</dt>
<dd></dd>
<dt>VERSION 2.1
</dt>
<dd></dd>
<dt>VERSION 2.2
</dt>
<dd>Specifies the default IPP version number to use for the tests that follow.

</dd>
</dl>
<h2 class="title"><a name="TEST_DIRECTIVES">Test Directives</a></h2>
The following directives are understood in a test:
<dl>
<dt>ATTR tag attribute-name value(s)
</dt>
<dd>Adds an attribute to the test request. Values are separated by the comma (",")
character - escape commas using the "" character.
</dd>
<dt>ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ]
</dt>
<dd>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.
</dd>
<dt>DELAY seconds
</dt>
<dd>Specifies a delay before this test will be run.
</dd>
<dt>DISPLAY attribute-name
</dt>
<dd>Specifies that value of the named attribute should be output as part of the
test report.
</dd>
<dt>EXPECT attribute-name [ predicate(s) ]
</dt>
<dd></dd>
<dt>EXPECT ?attribute-name predicate(s)
</dt>
<dd></dd>
<dt>EXPECT !attribute-name
</dt>
<dd>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.
</dd>
<dt>FILE filename
</dt>
<dd>Specifies a file to include at the end of the request. This is typically used
when sending a test print file.
</dd>
<dt>GROUP tag
</dt>
<dd>Specifies the group tag for subsequent attributes in the request.
</dd>
<dt>IGNORE-ERRORS yes
</dt>
<dd></dd>
<dt>IGNORE-ERRORS no
</dt>
<dd>Specifies whether <i>ipptool</i> will ignore errors and continue with subsequent
tests.
</dd>
<dt>NAME "literal string"
</dt>
<dd>Specifies the human-readable name of the test.
</dd>
<dt>OPERATION operation-code
</dt>
<dd>Specifies the operation to be performed.
</dd>
<dt>REQUEST-ID number
</dt>
<dd></dd>
<dt>REQUEST-ID random
</dt>
<dd>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).
</dd>
<dt>RESOURCE path
</dt>
<dd>Specifies an alternate resource path that is used for the HTTP POST request.
The default is the resource from the URI provided to the <i>ipptool</i> program.
</dd>
<dt>SKIP-IF-DEFINED variable-name
</dt>
<dd></dd>
<dt>SKIP-IF-NOT-DEFINED variable-name
</dt>
<dd>Specifies that the current test should be skipped when the variable is or is not
defined.
</dd>
<dt>SKIP-PREVIOUS-ERROR yes
</dt>
<dd></dd>
<dt>SKIP-PREVIOUS-ERROR no
</dt>
<dd>Specifies whether <i>ipptool</i> will skip the current test if the previous test
resulted in an error/failure.
</dd>
<dt>STATUS status-code [ predicate ]
</dt>
<dd>Specifies an expected response status-code value. Additional requirements can be
added as predicates - see the "STATUS PREDICATES" section for more information
on predicates.
</dd>
<dt>TRANSFER auto
</dt>
<dd>Specifies that this test will use "Transfer-Encoding: chunked" if it has an
attached file or "Content-Length:" otherwise.
</dd>
<dt>TRANSFER chunked
</dt>
<dd>Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked"
header.
</dd>
<dt>TRANSFER length
</dt>
<dd>Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
</dd>
<dt>VERSION 1.0
</dt>
<dd></dd>
<dt>VERSION 1.1
</dt>
<dd></dd>
<dt>VERSION 2.0
</dt>
<dd></dd>
<dt>VERSION 2.1
</dt>
<dd></dd>
<dt>VERSION 2.2
</dt>
<dd>Specifies the IPP version number to use for this test.

</dd>
</dl>
<h2 class="title"><a name="EXPECT_PREDICATES">Expect Predicates</a></h2>
The following predicates are understood following the EXPECT test directive:
<dl>
<dt>COUNT number
</dt>
<dd>Requires the EXPECT attribute to have the specified number of values.
</dd>
<dt>DEFINE-MATCH variable-name
</dt>
<dd>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.
</dd>
<dt>DEFINE-NO-MATCH variable-name
</dt>
<dd>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.
</dd>
<dt>DEFINE-VALUE variable-name
</dt>
<dd>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.
</dd>
<dt>IF-DEFINED variable-name
</dt>
<dd>Makes the EXPECT conditions apply only if the specified variable is defined.
</dd>
<dt>IF-NOT-DEFINED variable-name
</dt>
<dd>Makes the EXPECT conditions apply only if the specified variable is not
defined.
</dd>
<dt>IN-GROUP tag
</dt>
<dd>Requires the EXPECT attribute to be in the specified group tag.
</dd>
<dt>OF-TYPE tag[,tag,...]
</dt>
<dd>Requires the EXPECT attribute to use the specified value tag(s).
</dd>
<dt>REPEAT-MATCH
</dt>
<dd></dd>
<dt>REPEAT-NO-MATCH
</dt>
<dd>Specifies that the current test should be repeated when the EXPECT condition
matches or does not match.
</dd>
<dt>SAME-COUNT-AS attribute-name
</dt>
<dd>Requires the EXPECT attribute to have the same number of values as the specified
parallel attribute.
</dd>
<dt>WITH-ALL-VALUES "literal string"
</dt>
<dd>Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.
</dd>
<dt>WITH-ALL-VALUES &lt;number
</dt>
<dd></dd>
<dt>WITH-ALL-VALUES =number
</dt>
<dd></dd>
<dt>WITH-ALL-VALUES >number
</dt>
<dd></dd>
<dt>WITH-ALL-VALUES number[,number,...]
</dt>
<dd>Requires that all values of the EXPECT attribute match the number(s) or numeric comparison. When comparing rangeOfInteger values, the "&lt;" and ">" operators only check the upper bound of the range.
</dd>
<dt>WITH-ALL-VALUES "false"
</dt>
<dd></dd>
<dt>WITH-ALL-VALUES "true"
</dt>
<dd>Requires that all values of the EXPECT attribute match the boolean value given.
</dd>
<dt>WITH-ALL-VALUES "/regular expression/"
</dt>
<dd>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.
</dd>
<dt>WITH-VALUE "literal string"
</dt>
<dd>Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.
</dd>
<dt>WITH-VALUE &lt;number
</dt>
<dd></dd>
<dt>WITH-VALUE =number
</dt>
<dd></dd>
<dt>WITH-VALUE >number
</dt>
<dd></dd>
<dt>WITH-VALUE number[,number,...]
</dt>
<dd>Requires that at least one value of the EXPECT attribute matches the number(s) or numeric comparison. When comparing rangeOfInteger values, the "&lt;" and ">" operators only check the upper bound of the range.
</dd>
<dt>WITH-VALUE "false"
</dt>
<dd></dd>
<dt>WITH-VALUE "true"
</dt>
<dd>Requires that at least one value of the EXPECT attribute matches the boolean value given.
</dd>
<dt>WITH-VALUE "/regular expression/"
</dt>
<dd>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.

</dd>
</dl>
<h2 class="title"><a name="STATUS_PREDICATES">Status Predicates</a></h2>
The following predicates are understood following the STATUS test directive:
<dl>
<dt>IF-DEFINED variable-name
</dt>
<dd>Makes the STATUS apply only if the specified variable is defined.
</dd>
<dt>IF-NOT-DEFINED variable-name
</dt>
<dd>Makes the STATUS apply only if the specified variable is not defined.
</dd>
<dt>REPEAT-MATCH
</dt>
<dd></dd>
<dt>REPEAT-NO-MATCH
</dt>
<dd>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.

</dd>
</dl>
<h2 class="title"><a name="OPERATION_CODES">Operation Codes</a></h2>
Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from
RFC 2911 and other IPP extension specifications. Here is a complete list:
<pre>
    Activate-Printer
    CUPS-Accept-Jobs
    CUPS-Add-Modify-Class
    CUPS-Add-Modify-Printer
    CUPS-Authenticate-Job
    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
    Cancel-Current-Job
    Cancel-Job
    Cancel-Jobs
    Cancel-My-Jobs
    Cancel-Subscription
    Close-Job
    Create-Job
    Create-Job-Subscription
    Create-Printer-Subscription
    Deactivate-Printer
    Disable-Printer
    Enable-Printer
    Get-Job-Attributes
    Get-Jobs
    Get-Notifications
    Get-Printer-Attributes
    Get-Printer-Support-Files
    Get-Printer-Supported-Values
    Get-Subscription-Attributes
    Get-Subscriptions
    Hold-Job
    Hold-New-Jobs
    Identify-Printer
    Pause-Printer
    Pause-Printer-After-Current-Job
    Print-Job
    Print-URI
    Promote-Job
    Purge-Jobs
    Release-Held-New-Jobs
    Release-Job
    Renew-Subscription
    Reprocess-Job
    Restart-Job
    Restart-Printer
    Resubmit-Job
    Resume-Job
    Resume-Printer
    Schedule-Job-After
    Send-Document
    Send-Notifications
    Send-URI
    Set-Job-Attributes
    Set-Printer-Attributes
    Shutdown-Printer
    Startup-Printer
    Suspend-Current-Job
    Validate-Document
    Validate-Job
</pre>

<h2 class="title"><a name="STATUS_CODES">Status Codes</a></h2>
Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC
2911 and other IPP extension specifications. Here is a complete list:
<pre>
    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-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-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
</pre>

<h2 class="title"><a name="TAGS">Tags</a></h2>
Value and group tags correspond to the names from RFC 2911 and other IPP
extension specifications. Here are the group tags:
<pre>
    event-notification-attributes-tag
    job-attributes-tag
    operation-attributes-tag
    printer-attributes-tag
    subscription-attributes-tag
    unsupported-attributes-tag
</pre>
<p>Here are the value tags:
<pre>
    admin-define
    boolean
    charset
    collection
    dateTime
    default
    delete-attribute
    enum
    integer
    keyword
    mimeMediaType
    nameWithLanguage
    nameWithoutLanguage
    naturalLanguage
    no-value
    not-settable
    octetString
    rangeOfInteger
    resolution
    textWithLanguage
    textWithoutLanguage
    unknown
    unsupported
    uri
    uriScheme
</pre>

<h2 class="title"><a name="VARIABLES">Variables</a></h2>
The <i>ipptool</i> 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:
<dl>
<dt>$$
</dt>
<dd>Inserts a single "$" character.
</dd>
<dt>$ENV[name]
</dt>
<dd>Inserts the value of the named environment variable, or an empty string if the
environment variable is not defined.
</dd>
<dt>$filename
</dt>
<dd>Inserts the filename provided to <i>ipptool</i> with the "-f" option.
</dd>
<dt>$hostname
</dt>
<dd>Inserts the hostname from the URI provided to <i>ipptool</i>.
</dd>
<dt>$job-id
</dt>
<dd>Inserts the last job-id value returned in a test response or 0 if no job-id has
been seen.
</dd>
<dt>$job-uri
</dt>
<dd>Inserts the last job-uri value returned in a test response or an empty string if
no job-uri has been seen.
</dd>
<dt>$scheme
</dt>
<dd>Inserts the scheme from the URI provided to <i>ipptool</i>.
</dd>
<dt>$notify-subscription-id
</dt>
<dd>Inserts the last notify-subscription-id value returnd in a test response or 0 if
no notify-subscription-id has been seen.
</dd>
<dt>$port
</dt>
<dd>Inserts the port number from the URI provided to <i>ipptool</i>.
</dd>
<dt>$resource
</dt>
<dd>Inserts the resource path from the URI provided to <i>ipptool</i>.
</dd>
<dt>$uri
</dt>
<dd>Inserts the URI provided to <i>ipptool</i>.
</dd>
<dt>$user
</dt>
<dd>Inserts the current user's login name.
</dd>
<dt>$username
</dt>
<dd>Inserts the username from the URI provided to <i>ipptool</i>, if any.

</dd>
</dl>
<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
<a href='man-ipptool.html?TOPIC=Man+Pages'>ipptool(1)</a>,
<br>
<a href='http://localhost:631/help'>http://localhost:631/help</a>

<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
Copyright 2007-2012 by Apple Inc.

</body>
</html>
Commit	Line	Data
a2326b5b MS	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	2	<html>
	3	<!-- SECTION: Man Pages -->
	4	<head>
	5	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	6	<title>ipptoolfile(5)</title>
	7	</head>
	8	<body>
	9	<h1 class="title">ipptoolfile(5)</h1>
	10	<h2 class="title"><a name="NAME">Name</a></h2>
	11	ipptoolfile - ipptool file format
	12
	13	<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
	14	The <a href='man-ipptool.html?TOPIC=Man+Pages'>ipptool(1)</a> 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 curley braces, for example:
	15	<pre>
	16
	17	# This is a comment
	18	{
	19	# The name of the test
	20	NAME "Print PostScript Job"
	21
	22	# The request to send
	23	OPERATION Print-Job
	24	GROUP operation-attributes-tag
	25	ATTR charset attributes-charset utf-8
	26	ATTR language attributes-natural-language en
	27	ATTR uri printer-uri $uri
	28	ATTR name requesting-user-name $user
	29	FILE testfile.ps
	30
	31	# The response to expect
	32	STATUS successful-ok
	33	EXPECT attributes-charset OF-TYPE charset
	34	EXPECT attributes-natural-language OF-TYPE naturalLanguage
	35	EXPECT job-id OF-TYPE integer
	36	EXPECT job-uri OF-TYPE uri
	37	}
	38	{
	39	# The name of the test
	40	NAME "Get Attributes of PostScript Job"
	41
	42	# The request to send
	43	OPERATION Get-Job-Attributes
	44	GROUP operation-attributes-tag
	45	ATTR charset attributes-charset utf-8
	46	ATTR language attributes-natural-language en
	47	ATTR uri printer-uri $uri
	48	ATTR integer job-id $job-id
	49	ATTR name requesting-user-name $user
	50
	51	# The response to expect
	52	STATUS successful-ok
	53	EXPECT attributes-charset OF-TYPE charset
	54	EXPECT attributes-natural-language OF-TYPE naturalLanguage
	55	EXPECT job-id OF-TYPE integer
	56	EXPECT job-uri OF-TYPE uri
	57	EXPECT job-state OF-TYPE enum
	58	EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user"
	59	}
	60	</pre>
	61
	62	<h2 class="title"><a name="TOP-LEVEL_DIRECTIVES">Top-level Directives</a></h2>
	63	The following directives can be used outside of a test:
	64	<dl>
65	<dt>{ test }
66	</dt>
67	<dd>Defines a test.
68	</dd>
69	<dt>DEFINE variable-name value
70	</dt>
71	<dd>Defines the named variable to the given value. This is equivalent to specifying
72	"-d variable-name=value" on the <i>ipptool</i> command-line.
73	</dd>
74	<dt>DEFINE-DEFAULT variable-name value
75	</dt>
76	<dd>Defines the named variable to the given value if it does not already have a
77	value.
78	</dd>
79	<dt>IGNORE-ERRORS yes
80	</dt>
81	<dd></dd>
82	<dt>IGNORE-ERRORS no
83	</dt>
84	<dd>Specifies whether, by default, <i>ipptool</i> will ignore errors and continue with
85	subsequent tests.
86	</dd>
87	<dt>INCLUDE "filename"
88	</dt>
89	<dd></dd>
90	<dt>INCLUDE <filename>
91	</dt>
92	<dd>Includes another test file. The first form includes a file relative to the
93	current test file, while the second form includes a file from the <i>ipptool</i>
94	include directory.
95	</dd>
96	<dt>INCLUDE-IF-DEFINED name "filename"
97	</dt>
98	<dd></dd>
99	<dt>INCLUDE-IF-DEFINED name <filename>
100	</dt>
101	<dd>Includes another test file if the named variable is defined. The first form
102	includes a file relative to the current test file, while the second form
103	includes a file from the <i>ipptool</i> include directory.
104	</dd>
105	<dt>INCLUDE-IF-NOT-DEFINED name "filename"
106	</dt>
107	<dd></dd>
108	<dt>INCLUDE-IF-NOT-DEFINED name <filename>
109	</dt>
110	<dd>Includes another test file if the named variable is not defined. The first form
111	includes a file relative to the current test file, while the second form
112	includes a file from the <i>ipptool</i> include directory.
113	</dd>
114	<dt>SKIP-IF-DEFINED variable-name
115	</dt>
116	<dd></dd>
117	<dt>SKIP-IF-NOT-DEFINED variable-name
118	</dt>
119	<dd>Specifies that the remainder of the test file should be skipped when the
120	variable is or is not defined.
121	</dd>
122	<dt>TRANSFER auto
123	</dt>
124	<dd>Specifies that tests will, by default, use "Transfer-Encoding: chunked" for
125	requests with attached files and "Content-Length:" for requests without attached
126	files.
127	</dd>
128	<dt>TRANSFER chunked
129	</dt>
130	<dd>Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding:
131	chunked" header. This is the default and is equivalent to specifying "-c" on the
132	<i>ipptool</i> command-line. Support for chunked requests is required for
133	conformance with all versions of IPP.
134	</dd>
135	<dt>TRANSFER length
136	</dt>
137	<dd>Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:"
138	header. This is equivalent to specifying "-l" on the <i>ipptool</i> command-line.
139	Support for content length requests is required for conformance with all
140	versions of IPP.
141	</dd>
142	<dt>VERSION 1.0
143	</dt>
144	<dd></dd>
145	<dt>VERSION 1.1
146	</dt>
147	<dd></dd>
148	<dt>VERSION 2.0
149	</dt>
150	<dd></dd>
151	<dt>VERSION 2.1
152	</dt>
153	<dd></dd>
154	<dt>VERSION 2.2
155	</dt>
156	<dd>Specifies the default IPP version number to use for the tests that follow.
157
158	</dd>
159	</dl>
160	<h2 class="title"><a name="TEST_DIRECTIVES">Test Directives</a></h2>
161	The following directives are understood in a test:
162	<dl>
163	<dt>ATTR tag attribute-name value(s)
164	</dt>
165	<dd>Adds an attribute to the test request. Values are separated by the comma (",")
166	character - escape commas using the "" character.
167	</dd>
168	<dt>ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ]
169	</dt>
170	<dd>Adds a collection attribute to the test request. Member attributes follow the
171	same syntax as regular attributes and can themselves be nested collections.
172	Multiple collection values can be supplied as needed.
173	</dd>
174	<dt>DELAY seconds
175	</dt>
176	<dd>Specifies a delay before this test will be run.
177	</dd>
178	<dt>DISPLAY attribute-name
179	</dt>
180	<dd>Specifies that value of the named attribute should be output as part of the
181	test report.
182	</dd>
183	<dt>EXPECT attribute-name [ predicate(s) ]
184	</dt>
185	<dd></dd>
186	<dt>EXPECT ?attribute-name predicate(s)
187	</dt>
188	<dd></dd>
189	<dt>EXPECT !attribute-name
190	</dt>
191	<dd>Specifies that the response must/may/must not include the named attribute.
192	Additional requirements can be added as predicates - see the "EXPECT PREDICATES"
193	section for more information on predicates.
194	</dd>
195	<dt>FILE filename
196	</dt>
197	<dd>Specifies a file to include at the end of the request. This is typically used
198	when sending a test print file.
199	</dd>
200	<dt>GROUP tag
201	</dt>
202	<dd>Specifies the group tag for subsequent attributes in the request.
203	</dd>
204	<dt>IGNORE-ERRORS yes
205	</dt>
206	<dd></dd>
207	<dt>IGNORE-ERRORS no
208	</dt>
209	<dd>Specifies whether <i>ipptool</i> will ignore errors and continue with subsequent
210	tests.
211	</dd>
212	<dt>NAME "literal string"
213	</dt>
214	<dd>Specifies the human-readable name of the test.
215	</dd>
216	<dt>OPERATION operation-code
217	</dt>
218	<dd>Specifies the operation to be performed.
219	</dd>
220	<dt>REQUEST-ID number
221	</dt>
222	<dd></dd>
223	<dt>REQUEST-ID random
224	</dt>
225	<dd>Specifies the request-id value to use in the request, either an integer or the
226	word "random" to use a randomly generated value (the default).
227	</dd>
228	<dt>RESOURCE path
229	</dt>
230	<dd>Specifies an alternate resource path that is used for the HTTP POST request.
231	The default is the resource from the URI provided to the <i>ipptool</i> program.
232	</dd>
233	<dt>SKIP-IF-DEFINED variable-name
234	</dt>
235	<dd></dd>
236	<dt>SKIP-IF-NOT-DEFINED variable-name
237	</dt>
238	<dd>Specifies that the current test should be skipped when the variable is or is not
239	defined.
240	</dd>
241	<dt>SKIP-PREVIOUS-ERROR yes
242	</dt>
243	<dd></dd>
244	<dt>SKIP-PREVIOUS-ERROR no
245	</dt>
246	<dd>Specifies whether <i>ipptool</i> will skip the current test if the previous test
247	resulted in an error/failure.
248	</dd>
249	<dt>STATUS status-code [ predicate ]
250	</dt>
251	<dd>Specifies an expected response status-code value. Additional requirements can be
252	added as predicates - see the "STATUS PREDICATES" section for more information
253	on predicates.
254	</dd>
255	<dt>TRANSFER auto
256	</dt>
257	<dd>Specifies that this test will use "Transfer-Encoding: chunked" if it has an
258	attached file or "Content-Length:" otherwise.
259	</dd>
260	<dt>TRANSFER chunked
261	</dt>
262	<dd>Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked"
263	header.
264	</dd>
265	<dt>TRANSFER length
266	</dt>
267	<dd>Specifies that this test will use the HTTP/1.0 "Content-Length:" header.
268	</dd>
269	<dt>VERSION 1.0
270	</dt>
271	<dd></dd>
272	<dt>VERSION 1.1
273	</dt>
274	<dd></dd>
275	<dt>VERSION 2.0
276	</dt>
277	<dd></dd>
278	<dt>VERSION 2.1
279	</dt>
280	<dd></dd>
281	<dt>VERSION 2.2
282	</dt>
283	<dd>Specifies the IPP version number to use for this test.
284
285	</dd>
286	</dl>
287	<h2 class="title"><a name="EXPECT_PREDICATES">Expect Predicates</a></h2>
288	The following predicates are understood following the EXPECT test directive:
289	<dl>
290	<dt>COUNT number
291	</dt>
292	<dd>Requires the EXPECT attribute to have the specified number of values.
293	</dd>
294	<dt>DEFINE-MATCH variable-name
295	</dt>
296	<dd>Defines the variable to "1" when the EXPECT condition matches. A side-effect of
297	this predicate is that this EXPECT will never fail a test.
298	</dd>
299	<dt>DEFINE-NO-MATCH variable-name
300	</dt>
301	<dd>Defines the variable to "1" when the EXPECT condition does not match. A side-
302	effect of this predicate is that this EXPECT will never fail a test.
303	</dd>
304	<dt>DEFINE-VALUE variable-name
305	</dt>
306	<dd>Defines the variable to the value of the attribute when the EXPECT condition
307	matches. A side-effect of this predicate is that this EXPECT will never fail a test.
308	</dd>
309	<dt>IF-DEFINED variable-name
310	</dt>
311	<dd>Makes the EXPECT conditions apply only if the specified variable is defined.
312	</dd>
313	<dt>IF-NOT-DEFINED variable-name
314	</dt>
315	<dd>Makes the EXPECT conditions apply only if the specified variable is not
316	defined.
317	</dd>
318	<dt>IN-GROUP tag
319	</dt>
320	<dd>Requires the EXPECT attribute to be in the specified group tag.
321	</dd>
322	<dt>OF-TYPE tag[,tag,...]
323	</dt>
324	<dd>Requires the EXPECT attribute to use the specified value tag(s).
325	</dd>
326	<dt>REPEAT-MATCH
327	</dt>
328	<dd></dd>
329	<dt>REPEAT-NO-MATCH
330	</dt>
331	<dd>Specifies that the current test should be repeated when the EXPECT condition
332	matches or does not match.
333	</dd>
334	<dt>SAME-COUNT-AS attribute-name
335	</dt>
336	<dd>Requires the EXPECT attribute to have the same number of values as the specified
337	parallel attribute.
338	</dd>
82cc1f9a MS	339	<dt>WITH-ALL-VALUES "literal string"
	340	</dt>
	341	<dd>Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive.
	342	</dd>
	343	<dt>WITH-ALL-VALUES <number
	344	</dt>
	345	<dd></dd>
	346	<dt>WITH-ALL-VALUES =number
	347	</dt>
	348	<dd></dd>
	349	<dt>WITH-ALL-VALUES >number
	350	</dt>
	351	<dd></dd>
	352	<dt>WITH-ALL-VALUES number[,number,...]
	353	</dt>
	354	<dd>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.
	355	</dd>
	356	<dt>WITH-ALL-VALUES "false"
	357	</dt>
	358	<dd></dd>
	359	<dt>WITH-ALL-VALUES "true"
	360	</dt>
	361	<dd>Requires that all values of the EXPECT attribute match the boolean value given.
	362	</dd>
	363	<dt>WITH-ALL-VALUES "/regular expression/"
	364	</dt>
	365	<dd>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.
	366	</dd>
a2326b5b MS	367	<dt>WITH-VALUE "literal string"
a2326b5b MS	368	</dt>
82cc1f9a MS	369	<dd>Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive.
	370	</dd>
	371	<dt>WITH-VALUE <number
	372	</dt>
	373	<dd></dd>
	374	<dt>WITH-VALUE =number
	375	</dt>
	376	<dd></dd>
	377	<dt>WITH-VALUE >number
	378	</dt>
	379	<dd></dd>
	380	<dt>WITH-VALUE number[,number,...]
	381	</dt>
	382	<dd>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.
	383	</dd>
	384	<dt>WITH-VALUE "false"
	385	</dt>
	386	<dd></dd>
	387	<dt>WITH-VALUE "true"
	388	</dt>
	389	<dd>Requires that at least one value of the EXPECT attribute matches the boolean value given.
a2326b5b MS	390	</dd>
	391	<dt>WITH-VALUE "/regular expression/"
	392	</dt>
82cc1f9a	393	<dd>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.
a2326b5b MS	394
	395	</dd>
	396	</dl>
	397	<h2 class="title"><a name="STATUS_PREDICATES">Status Predicates</a></h2>
	398	The following predicates are understood following the STATUS test directive:
	399	<dl>
	400	<dt>IF-DEFINED variable-name
	401	</dt>
	402	<dd>Makes the STATUS apply only if the specified variable is defined.
	403	</dd>
	404	<dt>IF-NOT-DEFINED variable-name
	405	</dt>
	406	<dd>Makes the STATUS apply only if the specified variable is not defined.
	407	</dd>
	408	<dt>REPEAT-MATCH
	409	</dt>
	410	<dd></dd>
	411	<dt>REPEAT-NO-MATCH
	412	</dt>
	413	<dd>Specifies that the current test should be repeated when the response status-code
	414	matches or does not match the value specified by the STATUS directive.
	415
	416	</dd>
	417	</dl>
	418	<h2 class="title"><a name="OPERATION_CODES">Operation Codes</a></h2>
	419	Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from
	420	RFC 2911 and other IPP extension specifications. Here is a complete list:
	421	<pre>
	422	Activate-Printer
	423	CUPS-Accept-Jobs
	424	CUPS-Add-Modify-Class
	425	CUPS-Add-Modify-Printer
	426	CUPS-Authenticate-Job
	427	CUPS-Delete-Class
	428	CUPS-Delete-Printer
	429	CUPS-Get-Classes
	430	CUPS-Get-Default
	431	CUPS-Get-Devices
	432	CUPS-Get-Document
	433	CUPS-Get-PPD
	434	CUPS-Get-PPDs
	435	CUPS-Get-Printers
	436	CUPS-Move-Job
	437	CUPS-Reject-Jobs
	438	CUPS-Set-Default
	439	Cancel-Current-Job
	440	Cancel-Job
	441	Cancel-Jobs
	442	Cancel-My-Jobs
	443	Cancel-Subscription
	444	Close-Job
	445	Create-Job
	446	Create-Job-Subscription
	447	Create-Printer-Subscription
	448	Deactivate-Printer
	449	Disable-Printer
	450	Enable-Printer
	451	Get-Job-Attributes
	452	Get-Jobs
	453	Get-Notifications
	454	Get-Printer-Attributes
	455	Get-Printer-Support-Files
	456	Get-Printer-Supported-Values
	457	Get-Subscription-Attributes
458	Get-Subscriptions
459	Hold-Job
460	Hold-New-Jobs
82cc1f9a	461	Identify-Printer
a2326b5b MS	462	Pause-Printer
	463	Pause-Printer-After-Current-Job
	464	Print-Job
	465	Print-URI
	466	Promote-Job
	467	Purge-Jobs
	468	Release-Held-New-Jobs
	469	Release-Job
	470	Renew-Subscription
	471	Reprocess-Job
	472	Restart-Job
	473	Restart-Printer
	474	Resubmit-Job
	475	Resume-Job
	476	Resume-Printer
	477	Schedule-Job-After
	478	Send-Document
	479	Send-Notifications
	480	Send-URI
	481	Set-Job-Attributes
	482	Set-Printer-Attributes
	483	Shutdown-Printer
	484	Startup-Printer
	485	Suspend-Current-Job
82cc1f9a	486	Validate-Document
a2326b5b MS	487	Validate-Job
	488	</pre>
	489
	490	<h2 class="title"><a name="STATUS_CODES">Status Codes</a></h2>
	491	Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC
	492	2911 and other IPP extension specifications. Here is a complete list:
	493	<pre>
	494	client-error-attributes-not-settable
	495	client-error-attributes-or-values-not-supported
	496	client-error-bad-request
	497	client-error-charset-not-supported
	498	client-error-compression-error
	499	client-error-compression-not-supported
	500	client-error-conflicting-attributes
	501	client-error-document-access-error
	502	client-error-document-format-error
	503	client-error-document-format-not-supported
82cc1f9a MS	504	client-error-document-password-error
	505	client-error-document-permission-error
	506	client-error-document-security-error
	507	client-error-document-unprintable-error
a2326b5b MS	508	client-error-forbidden
	509	client-error-gone
	510	client-error-ignored-all-notifications
	511	client-error-ignored-all-subscriptions
	512	client-error-not-authenticated
	513	client-error-not-authorized
	514	client-error-not-found
	515	client-error-not-possible
	516	client-error-print-support-file-not-found
	517	client-error-request-entity-too-large
	518	client-error-request-value-too-long
	519	client-error-timeout
	520	client-error-too-many-subscriptions
	521	client-error-uri-scheme-not-supported
	522	cups-see-other
	523	redirection-other-site
	524	server-error-busy
	525	server-error-device-error
	526	server-error-internal-error
	527	server-error-job-canceled
	528	server-error-multiple-document-jobs-not-supported
	529	server-error-not-accepting-jobs
	530	server-error-operation-not-supported
	531	server-error-printer-is-deactivated
	532	server-error-service-unavailable
	533	server-error-temporary-error
	534	server-error-version-not-supported
	535	successful-ok
	536	successful-ok-but-cancel-subscription
	537	successful-ok-conflicting-attributes
	538	successful-ok-events-complete
	539	successful-ok-ignored-notifications
	540	successful-ok-ignored-or-substituted-attributes
	541	successful-ok-ignored-subscriptions
	542	successful-ok-too-many-events
	543	</pre>
	544
	545	<h2 class="title"><a name="TAGS">Tags</a></h2>
	546	Value and group tags correspond to the names from RFC 2911 and other IPP
	547	extension specifications. Here are the group tags:
	548	<pre>
	549	event-notification-attributes-tag
	550	job-attributes-tag
	551	operation-attributes-tag
	552	printer-attributes-tag
	553	subscription-attributes-tag
	554	unsupported-attributes-tag
	555	</pre>
	556	<p>Here are the value tags:
	557	<pre>
	558	admin-define
	559	boolean
	560	charset
	561	collection
	562	dateTime
	563	default
	564	delete-attribute
	565	enum
	566	integer
	567	keyword
	568	mimeMediaType
	569	nameWithLanguage
	570	nameWithoutLanguage
	571	naturalLanguage
572	no-value
573	not-settable
574	octetString
575	rangeOfInteger
576	resolution
577	textWithLanguage
578	textWithoutLanguage
579	unknown
580	unsupported
581	uri
582	uriScheme
583	</pre>
584
585	<h2 class="title"><a name="VARIABLES">Variables</a></h2>
586	The <i>ipptool</i> program maintains a list of variables that can be used in any
587	literal string or attribute value by specifying "$variable-name". Aside from
588	variables defined using the "-d" option or "DEFINE" directive, the following
589	pre-defined variables are available:
590	<dl>
591	<dt>$$
592	</dt>
593	<dd>Inserts a single "$" character.
594	</dd>
595	<dt>$ENV[name]
596	</dt>
597	<dd>Inserts the value of the named environment variable, or an empty string if the
598	environment variable is not defined.
599	</dd>
600	<dt>$filename
601	</dt>
602	<dd>Inserts the filename provided to <i>ipptool</i> with the "-f" option.
603	</dd>
604	<dt>$hostname
605	</dt>
606	<dd>Inserts the hostname from the URI provided to <i>ipptool</i>.
607	</dd>
608	<dt>$job-id
609	</dt>
610	<dd>Inserts the last job-id value returned in a test response or 0 if no job-id has
611	been seen.
612	</dd>
613	<dt>$job-uri
614	</dt>
615	<dd>Inserts the last job-uri value returned in a test response or an empty string if
616	no job-uri has been seen.
617	</dd>
618	<dt>$scheme
619	</dt>
620	<dd>Inserts the scheme from the URI provided to <i>ipptool</i>.
621	</dd>
622	<dt>$notify-subscription-id
623	</dt>
624	<dd>Inserts the last notify-subscription-id value returnd in a test response or 0 if
625	no notify-subscription-id has been seen.
626	</dd>
627	<dt>$port
628	</dt>
629	<dd>Inserts the port number from the URI provided to <i>ipptool</i>.
630	</dd>
631	<dt>$resource
632	</dt>
633	<dd>Inserts the resource path from the URI provided to <i>ipptool</i>.
634	</dd>
635	<dt>$uri
636	</dt>
637	<dd>Inserts the URI provided to <i>ipptool</i>.
638	</dd>
639	<dt>$user
640	</dt>
641	<dd>Inserts the current user's login name.
642	</dd>
643	<dt>$username
644	</dt>
645	<dd>Inserts the username from the URI provided to <i>ipptool</i>, if any.
646
647	</dd>
648	</dl>
649	<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
650	<a href='man-ipptool.html?TOPIC=Man+Pages'>ipptool(1)</a>,
651	<br>
652	<a href='http://localhost:631/help'>http://localhost:631/help</a>
653
654	<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
82cc1f9a	655	Copyright 2007-2012 by Apple Inc.
a2326b5b MS	656
	657	</body>
	658	</html>