Skip to content

Online Forms Lifecycle Tasks

Online forms participate in the package management lifecycle. The following lifecycle tasks for forms are supported for general use:

  • Unfreeze Online Forms - PACKAGE FORMS UNFREEZE

  • Approve a Form - FORMS PKG APPROVE

  • Refreeze Online Forms - PACKAGE FORMS REFREEZE

  • Reject a Form - FORMS PKG REJECT

  • Submit a Form for Approval - FORMS PKG SUBMIT

  • Add Comments to a Form - FORMS PKG COMMENT

Unfreeze Online Forms - PACKAGE FORMS UNFREEZE

Serena XML lets you unfreeze online forms in a frozen package for online completion, approval, or other changes. Options exist to collectively unfreeze all online forms in a package or to selectively unfreeze only those forms named in the request.

The Serena XML service/scope/message tags for a package-level unfreeze message for online forms are:

<service name="PACKAGE">
<scope name="FORMS">
<message name="UNFREEZE">

These tags appear in both requests and replies.

Note

The forms unfreeze request takes the value "package" in the name attribute of the <service> tag because it is executed by the low-level package service. The forms-specific scope of the service is shown in the name attribute of the <scope> tag, which takes the value "forms".

PACKAGE FORMS UNFREEZE — Requests

The forms unfreeze function requires a package name in the <package> tag as input. It assumes a full unfreeze is requested unless you specify otherwise by supplying one or more form numbers. Select the desired unfreeze option as follows:

  • Full Unfreeze — Omit the <formNumber> and <listcount> tags to unfreeze all online forms in a package. This is the default.

  • Selective Unfreeze — Supply one or more form numbers in the <formNumber> tag to selectively unfreeze the identified forms.

The following example shows how you might code a selective forms unfreeze request. Data structure details for the <request> tag appear in Exhibit 10-1.

...

Example XML — PACKAGE FORMS UNFREEZE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="FORMS">
        <message name="UNFREEZE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
        <request>
            <package>ACTP000009</package>
            <listCount>0001</listCount>
            <formNumber>010</formNumber>
        </request>
        </message>
    </scope>
</service>

Exhibit 10-1. PACKAGE FORMS UNFREEZE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<formNumber> Optional 1 String (3), variable ZMF form ID of desired online form.
<listCount> Optional 0 - 1 Integer (3), variable Number of forms named in request. Must match number of tags. Value range: 1 - 800.
NOTE: Required for selective unfreeze or refreeze.
NOTE: If used, tag is also required.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.

PACKAGE FORMS UNFREEZE — Replies

The reply for a forms unfreeze message does not return a <result> data structure. It does, however, return a standard <response> data structure to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Refreeze Online Forms - PACKAGE FORMS REFREEZE

This function refreezes previously unfrozen online forms in package, preventing further change. Options exist to collectively refreeze all online forms in a package or to selectively refreeze only those forms named in the request.

The Serena XML service/scope/message tags for a package-level refreeze message for online forms are:

<service name=”PACKAGE”>
<scope name=”FORMS”>
<message name=”REFREEZE”>

These tags appear in both requests and replies.

Note

The forms refreeze request takes the value “package” in the name attribute of the <service> tag because it is executed by the low-level package service. The forms-specific scope of the service is shown in the name attribute of the <scope> tag, which takes the value “forms”.

PACKAGE FORMS REFREEZE — Requests

As with unfreeze requests, Serena XML supports two types of package-level refreeze requests for custom forms:

Select the desired unfreeze option as follows:

  • Full Refreeze — Omit the <formNumber> and <listcount> tags to unfreeze all online forms in a package. This is the default.
  • Selective Refreeze — Supply one or more form numbers in the <formNumber> tag (s) to selectively unfreeze the identified forms.

The <request> tag data structure for a forms refreeze request is identical to that for an forms unfreeze request. See Exhibit 10-1 for details.

PACKAGE FORMS REFREEZE — Replies

The reply for a forms refreeze message does not return a data structure. It does, however, return a standard data structure to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Submit a Form for Approval - FORMS PKG SUBMIT

Once an online form has been completed interactively in ISPF, Serena XML can automate its submission for approval. This function assumes that approvers, notifications, and variables associated with a specific form have previously been defined using online forms maintenance.

The Serena XML service/scope/message tags for a message to submit an online form for approve are:

<service name=”FORMS”>
<scope name=”PKG”>
<message name=”SUBMIT”>

These tags appear in both requests and replies.

FORMS PKG SUBMIT — Requests

Only one form may be submitted for approval at a time using Serena XML. Both the form number and the package where the desired instance of the form resides are required in the request. Data structure details for the tag appear in Exhibit 10-2.

Exhibit 10-2. FORMS PKG SUBMIT <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<formNumber> Required 1 String (3), variable ZMF form ID of desired online form.
<package> Required 1 String (10), fixed Fixed-format ZMF package name where desired instance of form resides.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.

FORMS PKG SUBMIT — Replies

The reply for a forms submit message does not return a <result> data structure. It does, however, return a standard <response> data structure to indicate the success or failure of the submit request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Approve a Form - FORMS PKG APPROVE

This function approves the action requested by a previously submitted online form. If approval of the form in the interactive ChangeMan ZMF environment would normally submit a job stream for execution, that same job stream is submitted for execution upon approval in Serena XML.

The Serena XML service/scope/message tags for a message to approve an online form are:

<service name=”FORMS”>
<scope name=”PKG”>
<message name=”APPROVE”>

These tags appear in both requests and replies.

FORMS PKG APPROVE — Requests

Only one form may be approved at a time using Serena XML. Both the form number and the package where the desired instance of the form resides are required in the request. Data structure details for the <request> tag appear in Exhibit 10-3.

Exhibit 10-3. Form Approval <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<formNumber> Required 1 String (3), variable ZMF form ID of desired online form.
<package> Required 1 String (10), fixed Fixed-format ZMF package name where desired instance of form resides.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.

FORMS PKG APPROVE — Replies

No <result> tags are returned in the Serena XML reply message for a form approval request. However, the reply message does return a standard <response> data element to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Reject a Form - FORMS PKG REJECT

This function rejects the action requested by a previously submitted online form. The form may not be open for concurrent use at the time it is rejected. Reject reasons are required.

To add reject reasons separately as comments, without actually rejecting the form request, use the online forms comment service. (See “Add Comments to a Form - FORMS PKG COMMENT”.) The Serena XML service/scope/message tags for an online form reject message are:

<service name=”FORMS”>
<scope name=”PKG”>
<message name=”REJECT”>

These tags appear in both requests and replies.

FORMS PKG REJECT — Requests

Requests to reject a form require a package name, form number, and at least one reason for the rejection. Only one form may be rejected at a time. Data structure details for the <request> tag appear in Exhibit 10-4.

Exhibit 10-4. FORMS PKG REJECT <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use instead of <applName> & <packageId>.
<formNumber> Required 1 String (3), variable ZMF form ID of desired online form.
<package> Required 1 String (10), fixed Fixed-format ZMF package name where desired instance of form resides.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<rejectReason01> Required 1 String (72), variable Text of reason for rejecting action requested by form. First of up to ten lines of text.
<rejectReason02> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Second of up to ten lines of text.
<rejectReason03> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Third of up to ten lines of text.
<rejectReason04> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Fourth of up to ten lines of text.
<rejectReason05> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Fifth of up to ten lines of text.
<rejectReason06> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Sixth of up to ten lines of text.
<rejectReason07> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Seventh of up to ten lines of text.
<rejectReason08> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Eighth of up to ten lines of text.
<rejectReason09> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Ninth of up to ten lines of text.
<rejectReason10> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Tenth of up to ten lines of text.

FORMS PKG REJECT — Replies

No <result> tags are returned in the Serena XML reply message for an online form rejection. However, the reply message does return a standard <response> data element to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Add Comments to a Form - FORMS PKG COMMENT

This function allows you to add free-format text reasons for rejecting the action requested by an online form without committing to a reject decision. The rejection action itself requires a separate service. (See Reject a Form - FORMS PKG REJECT.)

The Serena XML service/scope/message tags for an online form comment message are:

<service name=”FORMS”>
<scope name=”PKG”>
<message name=”COMMENT”>

These tags appear in both requests and replies.

FORMS PKG COMMENT — Requests

The request message for this function requires a package name, a form number, and at least one comment, which is assumed to be a reason for rejecting the requested action but need not be. Up to ten lines of comment text (reject reasons) are supported.

Data structure details for the <request> tag appear in Exhibit 10-5.

Exhibit 10-5. FORMS PKG COMMENT<request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use instead of <applName> & <packageId>.
<formNumber> Required 1 String (3), variable ZMF form ID of desired online form.
<package> Required 1 String (10), fixed Fixed-format ZMF package name where desired instance of form resides.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<rejectReason01> Required 1 String (72), variable Text of reason for rejecting action requested by form. First of up to ten lines of text.
<rejectReason02> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Second of up to ten lines of text.
<rejectReason03> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Third of up to ten lines of text.
<rejectReason04> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Fourth of up to ten lines of text.
<rejectReason05> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Fifth of up to ten lines of text.
<rejectReason06> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Sixth of up to ten lines of text.
<rejectReason07> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Seventh of up to ten lines of text.
<rejectReason08> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Eighth of up to ten lines of text.
<rejectReason09> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Ninth of up to ten lines of text.
<rejectReason10> Optional 0 - 1 String (72), variable Text of reason for rejecting action requested by form. Tenth of up to ten lines of text.

FORMS PKG COMMENT — Replies

No <result> tags are returned in the Serena XML reply message for an online form comment. However, the reply message does return a standard <response> data element to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.