DOCUMENT CREATE

Create a document.

Read syntax diagramSkip visual syntax diagram
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.