Create a document.

DOCUMENT CREATE
>>-DOCUMENT--CREATE--DOCTOKEN(data-area)------------------------>
>--+----------------------------------------------+------------->
'-+-+-FROM(data-area)---+--LENGTH(data-area)-+-'
| +-TEXT(data-area)---+ |
| '-BINARY(data-area)-' |
+-FROMDOC(data-area)-----------------------+
'-TEMPLATE(name)---------------------------'
>--+-----------------------------------------------------------------------------------------+-->
'-SYMBOLLIST(data-area)--LISTLENGTH(data-value)--+-----------------------+--+-----------+-'
'-DELIMITER(data-value)-' '-UNESCAPED-'
>--+--------------------+--+--------------------+--------------><
'-DOCSIZE(data-area)-' '-HOSTCODEPAGE(name)-'
Conditions: INVREQ, NOTFND, SYMBOLERR, TEMPLATERR
This command is threadsafe.
Description
DOCUMENT CREATE signals the start of
the document creation process. The document being created can be an empty
document, or it can be based on an existing document, a template, or data
contained in an application buffer.
Options
- BINARY(data-area)
- specifies a buffer of data which is to be used as the contents of the
new document being created. The data is copied unchanged to the document content
and no attempt is made to parse the data for symbol substition. The purpose
of the BINARY option is to allow the application to insert blocks of data
that must not undergo conversion to a client code page when the data is sent. Use
the LENGTH option to specify the length of this buffer.
- DELIMITER(data-value)
- specifies an optional 1–byte value used to delimit symbol name-value pairs
in the SYMBOLLIST buffer. If this option is not specified, the value defaults
to an ampersand. There are several disallowed DELIMITER values, all of which
cause an INVREQ condition if used. The disallowed values are:
- null (binary X'00')
- shift in (binary X'0E')
- shift out (binary X'0F')
- space (binary X'40')
- plus sign (binary X'4E')
- colon (binary X'7A')
- equals (binary X'7E')
- percent sign (binary X'6C')
- backslash (binary X'E0')
If this option is used, the application must ensure that the DELIMITER
does not appear in any symbol value in the SYMBOLLIST buffer. For this reason,
the application should not use alphanumeric and other printable characters
as the DELIMITER value.
- DOCSIZE(data-area)
- specifies a binary fullword area that will be updated with the current
size of the document in bytes. This is the maximum size of the buffer needed
to contain a copy of the document when a RETRIEVE command is issued.
- DOCTOKEN(data-area)
- specifies a data area to contain the symbolic name of the document. The
area must be 16 bytes in length and will be set to a CICS®-generated name
by which the document can be referred to in later commands.
- FROM(data-area)
- specifies that data supplied by the application is to be used to create
the contents of the new document. The data content could be a template or
a document which was created and retrieved. If the data is a template, symbol
substitution will take place where the symbols exist in the symbol table.
If the data is a previously retrieved document, the conversion and bookmark
tags which were inserted during retrieval will be removed from the content
and stored in the internal format required by the API commands. Note that
symbol substitution will not be attempted on any unresolved symbols contained
in a retrieved document. Use the LENGTH option to specify the length of
this buffer.
- FROMDOC(data-area)
- specifies the symbolic name (see the DOCTOKEN option) of a document
whose contents are to be copied to the new document being created. All bookmark
and conversion tags are copied to the new document. The symbol table will
be not be copied.
- HOSTCODEPAGE(name)
- specifies the name of the host codepage that the data being added is encoded
in. This option applies to the TEXT, SYMBOL and TEMPLATE options only. The
name must be eight characters long; if it is shorter than eight characters
it must be padded on the right with blanks.
- LENGTH(data-value)
- specifies the length, as a fullword binary value, of the buffer containing
the TEXT, BINARY or FROM data.
- LISTLENGTH(data-value)
- specifies the length, as a fullword binary value, of the symbol list.
- SYMBOLLIST(data-area)
- specifies
a buffer which contains a symbol list. Use the LISTLENGTH option to specify
the length of this buffer. A symbol list is a character string consisting
of one or more symbol definitions separated by ampersands. Each symbol definition
consists of a name, an equals sign, and a value. By default, symbols in
the symbol list are separated by the & character, but you can override
this by using the DELIMITER keyword to specify a different symbol separator.
Here is an example of a symbol list:
applid=IYCQ&jobname=test
The
following rules apply when setting symbols using a SYMBOLLIST:
- The name is case-sensitive. It may only contain uppercase and lowercase
letters, numbers, and the special characters dollar ('$'), underscore ('_'),
hyphen (-'), number sign ('#'), period ('.') and at sign ('@'). The name is
case-sensitive, so uppercase letters are regarded as different from lowercase
letters. Unlike the symbols in the template, the names in the symbol list
have neither an ampersand at the beginning, nor a semicolon at the end. For
example, the symbol &mytitle; in the template corresponds to the name mytitle in
the symbol list.
- The values in the symbol list can contain any characters. However, special
coding is required if you need to include the following characters in symbol
values in the symbol list:
- The character that you have used as the symbol separator (which defaults
to an ampersand, but can be overridden by use of the DELIMITER option).
- The plus sign and the percent sign.
You can use the percent sign, followed by two characters that are hexadecimal
digits (that is, 0–9, a-f, and A-F), to include characters such as these that
have a special meaning. When the value is put into the symbol table, a percent
sign and the two hexadecimal digits following it are interpreted as the EBCDIC
equivalent of the single ASCII character denoted by the two digits. %2B produces
a plus sign, %25 produces a percent sign, and %26 produces an ampersand. If
the characters following the percent sign are not two valid hexadecimal digits,
the percent sign and the following characters are put into the symbol table
as they appear in the symbol list. If you prefer not to use this special
coding, you can specify the UNESCAPED option. When you specify this option,
no conversion takes place, and the symbol values are put into the symbol table
exactly as you entered them. However, the UNESCAPED option does not allow
you to include the character that you have used as the symbol separator within
a symbol value in a symbol list. If you want to use the UNESCAPED option,
choose a symbol separator that will never be used within a symbol value.
- If you want to include spaces in a value, CICS allows you to use the space
character, a plus sign, or an escape sequence (%20). However, you cannot use
a plus sign or escape sequence when the UNESCAPED option is used. In this
case, you must only use a space character to indicate a space.
- TEMPLATE(name)
- specifies the 48-byte name of a template. The template must be defined
to CICS using RDO. If the name is shorter than 48 bytes, it must be padded
on the right with blanks.
Note: If you insert a template before the symbols
contained in it are set, the symbols will never be substituted. This can occur
if you create a document from a template without specifying a symbol list.
- TEXT(data-area)
- specifies a buffer of data which is to be used as the contents of the
new document being created. The data is copied unchanged to the document content
and no attempt is made to parse the data for symbol substition. The data will
be marked as requiring conversion to the client code page when the document
is sent. Use the LENGTH option to specify the length of this buffer.
- UNESCAPED
- prevents CICS from unescaping symbol values contained in the SYMBOLLIST
buffer. If this option is used, plus signs are not converted to spaces, and
sequences such %2B are not converted to single byte values.
The UNESCAPED
option does not allow you to include the character that you have used as the
symbol separator within a symbol value in a symbol list. If you want to use
the UNESCAPED option, choose a symbol separator that will never be used within
a symbol value.
Conditions
- INVREQ
- RESP2 values are:
- 1
- The retrieved document specified on the FROM option is not in a valid
RETRIEVE format.
- NOTFND
- RESP2 values:
- 2
- The document specified on the FROMDOC option could not be found or was
named incorrectly.
- 3
- The template specified on the TEMPLATE option could not be found or was
named incorrectly.
- 7
- The host codepage specified on the HOSTCODEPAGE option could not be found
or was named incorrectly.
- 8
- The value specified for DELIMITER is not valid.
- SYMBOLERR
- a symbol specified in the symbol list does not conform to the naming rules
for symbols. RESP2 contains the offset of the symbol in the list.
- TEMPLATERR
- an invalid #set, #include or #echo command has been encountered while
processing the supplied template data. RESP2 contains the offset of the invalid
command.