DOCUMENT CREATE

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 substitution. 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. Certain delimiter values (such as the space character) are disallowed, and all of these cause an INVREQ condition on the command if used. The rules are listed in Rules for specifying symbols and symbol lists.

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 binary token 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 binary token (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 code page 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.

The standard CICS form of a host code page name consists of the code page number (or more generally CCSID) written using 3 to 5 decimal digits as necessary then padded with trailing spaces to 8 characters. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS now also accepts any decimal number of up to 8 digits (padded with trailing spaces) in the range 1 to 65535 as a code page name, even if it is not in the standard form.

Note that the HOSTCODEPAGE parameter must specify an EBCDIC-based code page if any symbol processing will be required, as the delimiters used for symbol and symbol list processing are assumed to be in EBCDIC.

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. Here is an example of a symbol list:

applid=IYCQ&jobname=test

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. Rules for specifying symbols and symbol lists lists the rules which apply when setting symbols using a SYMBOLLIST.

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 substitution. 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 value:

1

The retrieved document specified on the FROM option is not in a valid RETRIEVE format.

LENGERR

RESP2 value:

1

The value specified for LENGTH is invalid. The value is negative.

9

The value specified for LISTLENGTH is invalid. Value must be between 1 and (16M - 1).

70 NOTAUTH

The command has failed a resource security check. (If the NOTAUTH condition is not handled, applications that receive it may abend with code AEY7.)

Note that the EXEC CICS DOCUMENT commands reference document templates using the 48-character name of the template (as specified in the TEMPLATENAME attribute of the DOCTEMPLATE resource). However, security checking for the commands uses the name of the DOCTEMPLATE resource definition that corresponds to the TEMPLATENAME attribute. If resource security checking is in place, the user ID for the transaction must have READ access to this DOCTEMPLATE resource definition.

RESP2 value:

101

The user ID for the transaction does not have READ access to the DOCTEMPLATE resource definition for the document template named by the TEMPLATE option.

13 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.

116 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.

117 TEMPLATERR

The template specified on the DOCTEMPLATE resource does not exist or an invalid #set, #include or #echo command was encountered while processing the supplied template data. RESP2 contains the offset of the invalid command.